Christian Marquardt wrote: > Very nice! > >> """ >> one-line summary not using variable names or the function name > > I would personally prefer that the first name contains the function (but > nor arguments) - that way, when you are scrolling back in your terminal, > or have a version printed out, you know what function/method the > doc string belongs to without having to refer to examples lower down.
How are you viewing the docstrings that wouldn't associate the docstring with the function? >> A few sentences giving an extended description. > > After the general description, but before giving the inputs and outputs, > wouldn't it make sense to give the function signature as well? Something > like > > named, list, of, outputs = my_function(var1, variable2 [,kwdarg1=...]) > > This would again reduce the need to have an extra look into the example > section. Using the brackets, optional arguments and default settings > could also be communicated easily. Except for functions defined in C extension modules, the function signature is introspectable. All of the good ways of viewing docstring information already extract this data (help(), pydoc, epydoc, IPython's ? operator). Again, how are you viewing docstrings that you don't see this information already? -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
