parameter docstrings about qcodes HOT 15 CLOSED

Just got some ideas to what would be useful in a docstring

• text from the custom docstring (specify as an optional argument when initializing the parameter)
• ranges (or what is in the validator) (autogenerated)
• label and units from the parameter. (autogenerated)

from qcodes.

Another option would be the following: in add_parameter we create a subclass of StandardParameter (or whatever we create there) with a specialized docstring. In code it would be something like

# The normal parameter class
class Parameter():    
    def __init__(self):
        print('create Parameter class')

    def foo(self):
        print('hi there!')
    def bar(self):
        print('hello!')

m=Parameter()
help(m)


# If we need to add documentation, we create a derived class dynamically
# This can be done inside the add_parameter function

m1= type('Parameter', (Parameter,),  {'__doc__': 'my doc 1!'})
m2= type('Parameter', (Parameter,),  {'__doc__': 'my doc 2!'})

help(m2)

If this is the way to go I will adapt the code and make a PR.

from qcodes.

@eendebakpt cool idea - my only concern is whether this will be picklable for multiprocessing.

from qcodes.

@eendebakpt , would it be possible to inherit this custom class from whatever it is called from. The example I am thinking of is the manual parameter. I would like this function to work for that aswell.
I image the super() function allowing this sort of behaviour but I am not sure.

from qcodes.

@eendebakpt , I like your solution but I see one issue. If any instance of a parameter created using the add_parameter class creates a custom subclass it will not be possible to do any checks on type anymore. I'd say this is a minor issue at best but something we should consider before implementing this in any case.

Otherwise I guess this implementation will give the full functionality of docstrings (including the auto complete in notebooks) right?

from qcodes.

We are not there yet. Pickling does not work straight away (not sure why this is important), and type checking is hard (instance does not work either).

I think this is important to solve, having functions (and parameters) without documentation is not really acceptable.

import pickle

class Parameter():    
    def __init__(self):
        print('create Parameter class')

    def foo(self):
        print('hi there!')
    def bar(self):
        print('hello!')

m=Parameter()
help(m)


# If we need to add documentation, we create a derived class dynamically
# This can be done inside the add_parameter function

m1= type('Parameter', (Parameter,),  {'__doc__': 'my doc 1!'})
m2= type('Parameter', (Parameter,),  {'__doc__': 'my doc 2!'})

help(m2)

# not very informative...
print(type(m1))

isinstance(m1, Parameter) # false!

# This fails!
with open('test.pickle', 'wb'):
    pickle.dump( m1, open('test.bin', 'w') )

from qcodes.

Right, that's what I was afraid of. Pickling is necessary so that measurement loops, which run in a separate process, can use the parameter on Windows. And it doesn't work because it requires all classes to be importable, which this clearly isn't because it's defined dynamically.

Interestingly, though I still don't see a good solution for help(param), the jupyter shift-Tab tooltips do show instance variable docstrings:

so the simple solution that one would like to work, of just overriding __doc__ in the instance, isn't completely useless.

from qcodes.

In Spyder overriding __doc__ works in the console (but not the editor). I suggest we add a keyword to add_parameter and add_function to override the __doc__. This can do no harm as far as I can see, and it does help in some cases.

Overriding the build in help function is another option, but that might me more complicated.

from qcodes.

In #69 I have added the docstrings to the parameter and function classes. The Keithle drivers uses this only for the .nplc parameter, but if it works well I will add more docstrings. Could you please comment?

from qcodes.

@eendebakpt , I really like the ovewriting the instance doc, mostly because this is how I normally access and use docstrings.
@alexcjohnson I propose another addition, default docstrings. If docstring is None, automatically generate a docstring for an instrument that shows the following

• parameter label (if not None)
• units
• validator type
• validator min and max (if applicable)

This is information that is very convenient to have accessible at a press of tab and should be easy to implement.

from qcodes.

@AdriaanRol that sounds great - perhaps appending those to any provided docstring. What you want from the Validator should all be available from its repr. @eendebakpt do you want to add this to #69 ?

from qcodes.

@alexcjohnson and @eendebakpt , If we implement the default generated docstring in combination with what @eendebakpt implemented I propose we close this issue :)

from qcodes.

Agreed, as soon as we merge #69 lets close this.

from qcodes.

PR #69 is updated with comments made here and in the PR. The currently generated docstring is not very pretty, but sufficient for me. Feel free to improve on this if you want. If #69 is merged I will close the issue.

from qcodes.

#69 is in master.

from qcodes.