[Yt-dev] yt documentation, standards, implementation
Matthew Turk
matthewturk at gmail.com
Tue Jun 1 08:44:43 PDT 2010
Hi Sam,
> This is tricky because we have moved to *args, **kwargs for the arguments,
> and then the docstring does not explain what the args, kwargs are.
> Explicitly listing the arguments along with their types and a quick
> description would be invaluable to new users.
Agreed. In fact, that *specific* example is one I intend to get rid of:
http://yt.enzotools.org/ticket/242
But yes, where kwargs are unavoidable, they should be explicitly
listed in the docstring.
> As for the format of the docstrings, I am fine with the NumPy standard. I
> would suggest that whatever the standard becomes that there be a boilerplate
> example that can just be copied into any new function where developers can
> edit where necessary, and stick this example somewhere like the doc folder.
Yes, definitely. I intend to not only include a fiducial example like
the NumPy docs, but also a list of helpful mechanisms for
cross-referencing between objects, as well as idioms for describing
common patterns.
> Finally, since I do seem to read the majority of commits coming in, I'd be
> happy to be the guy to remind someone when their docstrings aren't up to
> snuff.
Great, thanks!
-Matt
More information about the yt-dev
mailing list