__doc__+= """Detailed description"""

[Steven D'Aprano]

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