|
From: | Dmitry Gutov |
Subject: | bug#20637: incompatible, undocumented change to vc-working-revision |
Date: | Sun, 17 Apr 2016 03:27:38 +0300 |
User-agent: | Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0 |
On 04/15/2016 04:23 PM, Michael Albinus wrote:
I'm not against this. But I would like to see the whole picture first. Where else unregistered is used, and whether we run into conflicts when using nil instead of unregistered.
Sure. I'm reasonably confident, but please take the time and do your own evaluation.
I disagree. The manual is the documentation for the users, to explain in depth, give examples, et cetera. The docstrings and VC's internal documentation have to stand on their own. It would be silly if the difference between `vc-backend' and `vc-responsible-backend' were to only be explained in the manual, but not in the docstrings.Are we speaking about different manuals? I'm speaking about the ‘GNU Emacs Lisp Reference Manual’, and not the ‘GNU Emacs Manual’ (the manual dedicated to users).
I've split off a tangent to emacs-devel. Emacs Lisp Reference is a counter-example, but I think the last sentence in my paragraph above is still correct.
VC has been documented in the docstrings and the Commentary sections (especially the one at the begining of vc.el). The new important information should go there first.
If then you'd like to create a manual based on that information, to present it in more digestible form, sure, but let's not put anything essential into the manual only. We might avoid publishing that manual, though, until we're sure that VC is rock-solid to build third-party code on.
That would also be unfair to people such as myself who prefer to consult the latter.With your argument, we could nuke the Emacs Lisp manual. Shall we?
Does your argument allow nuking all docstrings and comments?
So, do you need anything from me in this area? E.g., feel free to give a list of docstrings that seem insufficient to you, together with what you feel they are missing.I will start somehow, and show you for review.
Thanks.
I usually tease that kind of information out by reading the source code. Is there anything in particular I could help add to your understanding of the "global view"?Even if I understand it, it won't help any other developer. Let's document it.
Sure.
[Prev in Thread] | Current Thread | [Next in Thread] |