[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Docstrings and manuals
From: |
Dmitry Gutov |
Subject: |
Re: Docstrings and manuals |
Date: |
Sun, 17 Apr 2016 14:42:28 +0300 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0 |
On 04/17/2016 02:16 PM, Michael Albinus wrote:
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.
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"?
See also the Elisp Manual (info "(elisp)Caveats")
--8<---------------cut here---------------start------------->8---
The manual should be fully correct in what it does cover, and it is
therefore open to criticism on anything it says—from specific examples
and descriptive text, to the ordering of chapters and sections. If
something is confusing, or you find that you have to look at the sources
or experiment to learn something not covered in the manual, then perhaps
the manual should be fixed. Please let us know.
--8<---------------cut here---------------end--------------->8---
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).
- Docstrings and manuals, was: Re: bug#20637: incompatible, undocumented change to vc-working-revision, Dmitry Gutov, 2016/04/16
- 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 <=
- 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, 2016/04/17
- Re: Docstrings and manuals, Phillip Lord, 2016/04/18