[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.
- Re: Docstrings and manuals, (continued)
- Re: Docstrings and manuals, Eli Zaretskii, 2016/04/17
- RE: Docstrings and manuals, Drew Adams, 2016/04/17
- Re: Docstrings and manuals, Dmitry Gutov, 2016/04/17
- Re: Docstrings and manuals, Eli Zaretskii, 2016/04/17
- Re: Docstrings and manuals, Phillip Lord, 2016/04/18
- Re: Docstrings and manuals, Marcin Borkowski, 2016/04/18
- Re: Docstrings and manuals, Stefan Monnier, 2016/04/18
- Re: Docstrings and manuals, Marcin Borkowski, 2016/04/18
- Re: Docstrings and manuals,
Eli Zaretskii <=
- Re: Docstrings and manuals, Stefan Monnier, 2016/04/18
- Re: Docstrings and manuals, Eli Zaretskii, 2016/04/18
- Re: Docstrings and manuals, Eli Zaretskii, 2016/04/17
- Re: Docstrings and manuals, Dmitry Gutov, 2016/04/17
- Re: Docstrings and manuals, Eli Zaretskii, 2016/04/17
- Re: Docstrings and manuals, Dmitry Gutov, 2016/04/17
- Re: Docstrings and manuals, Eli Zaretskii, 2016/04/17
- Re: Docstrings and manuals, Richard Stallman, 2016/04/18
- Re: Docstrings and manuals, Dmitry Gutov, 2016/04/18
- Re: Docstrings and manuals, Richard Stallman, 2016/04/18