On Thu, 10 May 2012 02:36:29 +0000, Pierre Asselin wrote: > Hi. Started using python a few months back, still settling on my style. > I write docstrings and I use "pydoc mymodule" to refresh my memory. > > Problem: if I just docstring my classes/methods/functions the output of > pydoc more or less works as a reference manual, but if I get sidetracked > for even a few weeks I find that documentation inadequate when I return > to my code. I need to see some introductory context first, so that the > reference material makes sense.
It's very difficult to give advice on how to write docstrings when you are talking in such sweeping generalities. Perhaps what you are doing is perfectly fine, and perhaps it is terrible, but without seeing it, how can I tell? Nevertheless, I make some attempt to answer your questions below, although my answers will also be sweeping generalities. > Wery well, write a module docstring then. The problem now: the many > paragraphs of detailed description at the top of the module get in the > way. The pydoc output is good, but the code becomes hard to read. This does not follow. How does a docstring make the code hard to read? Just scroll past the docstring and read the code. Most good editors will colour-code the docstring differently from the actual code, but even if you're using Notepad (shudders), how hard can it be to scroll past a few paragraphs, or pages, of explanatory text in a docstring? I don't understand the nature of your problem here. If your module needs an explanatory module-level docstring to explain what it does, just give it one. > So I come up with this: > > ###################################################################### > #! env python > > """One-liner docstring.""" Why a one-liner? Why not put the detailed description here? > # Many classes, methods, functions, attributes, # with docstrings as > needed. Docs tend to be # short and the code speaks for itself. # Apparently not, since you find the docs insufficient. Perhaps the solution is not to have a huge module docstring and classes with short docstring, but to document the class in the class docstring instead of the module. > ... > # Much further down, > > ___doc___+= """ > > Detailed description goes here. Provide some context, explain what > the classes are for and what the most important methods are, give > simple examples, whatever. Say enough to make the rest > understandable.""" This sounds to me like *exactly* the sort of thing which belongs in the documentation for the classes themselves. The module docstring should document a high-level introduction and show some examples. Detailed description of what the classes do should be in the class docstring, detailed documentation of methods should be in the method docstring, and so forth. Also, as Ben suggests, you don't *have* to put all your documentation in the source code. You can also have a separate documentation document, such as a website or wiki. > if __name__ == "__main__": > # test code follows > ###################################################################### Have you considered turning your tests (at least some of them) into doctests? That way they act as both test and documentation at the same time: executable examples, in the docstrings themselves. > It seems to work, too. But is that a sound way to write python? Am I > relying on undocumented implementation details or am I safe? Are you referring to the part where you define a __doc__ string at the top of the module, and then add to it with __doc__ += "more text"? If not, it isn't clear to me what you mean. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
