Éric Araujo <mer...@netwok.org> added the comment: My general rule is that function/method docstrings are better short descriptions of what the function does and what the arguments are, a usage reminder for people who have already used the function. Classes docstrings can tell a bit more about how the class is supposed to be used, e.g. what particular responsibility they have and what they work with. Module docstrings should help you make sense of the public objects in the module, for example tell about the main classes and functions and briefly mentioning the less important ones.
This is a personal viewpoint; some people use dir and pydoc a lot to get the most info out of a new module, whereas I like separate documentation more. ElementTree has no docstrings at all, which is IMO bad; I’d like the javadoc comments to be turned into docstrings, and if they are too big they can be reduced to their core and the extra help moved to reST docs (which are at this moment in what looks like a good shape: they have the same info as the javadoc comments from a quick glance). I think some of the comments can just be deleted, like the @see lines. Finally, a note about the comments for attributes: they should be documented in the reST docs, and for the Python code you have two possibilities: you can document them in the class docstring, or put string literals after them (see http://www.python.org/dev/peps/pep-0258/#attribute-docstrings – they are discarded by Python, so not available to help/pydoc, but some tools can process them). ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue14006> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
