[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: |
Sun, 17 Apr 2016 18:14:45 +0300 |
> From: Dmitry Gutov <address@hidden>
> Date: Sun, 17 Apr 2016 16:12:05 +0300
> Cc: Glenn Morris <address@hidden>, emacs-devel <address@hidden>
>
> My problem is that you stated the lack of a manual as the reason for
> your lack of understanding of VC's internals. I'm saying the problem is
> them being documented insufficiently in the code. And, like I mentioned,
> if you go ahead and write the newfound revelations in the manual, but
> not anywhere else, a certain slice of developers is going to miss out.
yes, we should update both the doc strings and the manual(s).
> To put a different spin on my statement earlier: if neither the
> docstrings, nor the manual are considered the Single Source of Truth, to
> read a reasonably complete description of a function, I'd have to read
> both the docstring and the manual. And that's just wasteful.
>
> And even the personal preferences aside, we can't make the manual to be
> the SSOT because most functions are not documented there.
The doc strings and the manual should convey the same information,
where they both cover the same turf.
- 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, 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 <=
- 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
- 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