[Tutor] Documentation concerns.

[Magnus Lyckå]

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.

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?


--
Magnus Lycka (It's really Lyckå), magnus@thinkware.se
Thinkware AB, Sweden, www.thinkware.se
I code Python ~ The shortest path from thought to working program