Re: Docstrings and manuals

[Stefan Monnier]

>> FWIW, I like this idea.  I think we could reduce the amount of
>> "reference info" in the manual (a part that's already available in the
>> docstrings) by referring to the docstring instead, and instead increase
>> the amount of explanation giving tips/examples about how to use it.
> Then the manual will be a very awkward reading, even on-line.

Maybe we could just change the manual so it's not as
complete-and-definitive, but it's still self-standing (tho with easy
ways to get more details via docstrings).

> To say nothing of the fact that the current doc strings are usually
> much worse than the documentation in the manual.

Docstrings should (ideally) always be as complete as the manual, in the
sense that the actual info is there.  In practice, I find it's usually
the case.  But it's often present in a much rougher shape, indeed, so
you can only figure out that info after reading the manual to figure out
what the docstring really means.

> IOW, let's first make sure every changeset is accompanied by good
> documentation, and only then consider such significant changes.

Agreed,


        Stefan