[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 05:30:16 +0300 |
> Cc: address@hidden, address@hidden, address@hidden
> From: Dmitry Gutov <address@hidden>
> Date: Sun, 17 Apr 2016 22:59:21 +0300
>
> > IOW, writing a good manual is still a human activity that cannot be
> > easily automated. Ideally, doc strings should be phrased like
> > reference material, covering all the traits as tersely as possible,
> > while the manual should provide an easier reading with more continuity
> > text and even some explanations why things are the way they are. At
> > least IMO.
>
> That sounds fine, and maybe this way is best for the more complex
> subjects, but in general I'd prefer to see docstrings also written with
> readability in mind.
This would make them too long ad wordy, something we'd like to avoid,
I think.
- Re: Docstrings and manuals, (continued)
- Re: Docstrings and manuals, Michael Albinus, 2016/04/17
- Re: Docstrings and manuals, Dmitry Gutov, 2016/04/17
- Re: Docstrings and manuals, Michael Albinus, 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, Michael Albinus, 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, Drew Adams, 2016/04/17
- Re: Docstrings and manuals, Dmitry Gutov, 2016/04/17
- Re: Docstrings and manuals,
Eli Zaretskii <=
- 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, 2016/04/18
- 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