Re: Docstrings and manuals

[Eli Zaretskii]

> From: Stefan Monnier <address@hidden>
> Cc: address@hidden
> Date: Mon, 18 Apr 2016 15:33:20 -0400
> 
> >> 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).

I think going that way would need a way of inserting doc strings into
the displayed manual, which will require some infrastructure first.
Without having reference material, the manual won't be able to be
self-sufficient.

> > 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.

Indeed, in my experience I frequently need to read the manual to make
sense of the doc string.