[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Docstrings and manuals

From: Stefan Monnier
Subject: Re: Docstrings and manuals
Date: Mon, 18 Apr 2016 15:33:20 -0400
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux)

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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]