[Doc-SIG] Re: [Tutor] Documentation concerns.

Guido van Rossum guido@python.org
Wed May 28 18:57:34 2003


> There is currently a discussion about the Python documentation in
> the Tutor mailing list.
> 
> One issue in particular is whether the main documentation for
> the module should be in the module itself, rather than in a
> separate document.

This is a contentious issue that every project has to decide for
itself.

I personally think that documentation external to the code, while it
takes more time to create and maintain, can also be of better quality
than documentation maintained as part of the code.  I like to see
docstrings that serve as comments to the code and at the same time
serve as concise reference docs.

But every project has its own constraints, and I can certainly
understand why some projects prefer to have the full user
documentation as docstrings.  I expect that such projects will still
require some external documentation, e.g. a separate tutorial.

> What are the attitudes about this today? In PEP 287 it says:
> 
> "10. Will the docstrings in the Python standard library modules
>       be converted to reStructuredText?
> 
> No. Python's library reference documentation is maintained separately
> from the source. Docstrings in the Python standard library should not
> try to duplicate the library reference documentation. The current
> policy for docstrings in the Python standard library is that they
> should be no more than concise hints, simple and markup-free (although
> many do contain ad-hoc implicit markup)."
> 
> Is this still gospel? Any further thoughts around this?

This is still gospel for the Python standard library.

--Guido van Rossum (home page: http://www.python.org/~guido/)