[Top][All Lists]

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

Re: Docstrings and manuals

From: Eli Zaretskii
Subject: Re: Docstrings and manuals
Date: Mon, 18 Apr 2016 21:56:11 +0300

> From: Stefan Monnier <address@hidden>
> Date: Mon, 18 Apr 2016 11:47:17 -0400
> > I think that the two should have a different purpose. I would like more
> > "tutorial" information in the manual (in the sense of "here is a bit of
> > code that does something with the functions we are discussing at this
> > point"), while the docstrings should be the main documentation.
> > For myself, I think, being able to get to the docstring easily (probably
> > with a tooltip) from any occurrence of a function or variable in the
> > manual would be excellent.
> 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.

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

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]