[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Docstrings and manuals
From: |
Drew Adams |
Subject: |
RE: Docstrings and manuals |
Date: |
Sun, 17 Apr 2016 08:54:33 -0700 (PDT) |
> > > No primary or secondary. If docstring and manual are inconsistent, it
> > > is a bug which must be fixed.
> >
> > What's "inconsistent" in this case? They are almost always different.
>
> They can be different, but still consistent. There's more than one
> way to tell the same story, without contradicting the others.
>
> > > There is no automatism that the docstring is
> > > always right, and the manual is wrong in this case. It could be also
> > > vice versa.
> >
> > Wouldn't it be better if we had this "automatism"?
>
> No, not IMO.
>
> > I'm not arguing in favor of leaving mistakes in the manual. But I think
> > it should be strictly a derivative work. I.e. the docstrings must
> > contain the complete information (if maybe presented in a terse
> > fashion), and the manual could rephrase that, only to make it more
> > accessible (but not more informative).
>
> Once you allow rephrasing, you already allow deviation. And there
> really is no way around allowing it, because a manual that includes
> only the doc strings with a minimum "glue" is much less palatable.
> You can look at Guile as one example; GnuTLS is another. Such manuals
> are much less useful, IME, than what we have in Emacs.
>
> One thing that you will never find in doc strings is a discussion of
> merits and demerits of different ways of solving some problem,
> especially if such a discussion requires to jump back and forth
> between these ways, in order to make some point.
>
> 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.
+10 to what Eli and Michael are saying.
Neither doc string nor manual serves the purpose of
the other. The manual is not Javadoc.
It is up to humans to write the most appropriate text
for each, and to make coherent any differences in
message or presentation.
Differences should be based on the context (including
readers) and should not involve contradiction in
meaning (semantics, behavior) of the things described.
IOW, both need to be faithful descriptions of those
things. There can be differences in degree of
abstraction or of precision. But within a given level
of abstraction/precision, each must be a faithful
picture of the behavior it describes.
The same is true of any other communication about these
things to users, including tooltips and error messages:
The behavior/meaning of the program being described is
the same, and that needs to be reflected in a lack of
contradiction wrt description of that behavior/meaning.
- 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, 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 <=
- 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, 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