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

[Ian Bicking]

On Sat, 2003-05-24 at 05:53, Magnus Lyck=E5 wrote:
> One issue in particular is whether the main documentation for
> the module should be in the module itself, rather than in a
> separate document.

One issue I see with moving the documentation into the code, is that we
don't have any system that can represent the kind of documentation from
the standard library as docstrings.  Typically documentation created
from docstrings is highly (overly) structured, and does not allow items
to be introduced in an order different from the code, or presented with
a different structure than the code, plus there is no place for
narrative that is not connected with a function or class.

  Ian