[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Docstrings and manuals

From: Michael Albinus
Subject: Re: Docstrings and manuals
Date: Sun, 17 Apr 2016 18:39:18 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux)

Dmitry Gutov <address@hidden> writes:

> 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.
> To expand on my message in
> http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20637#91, an example:
> If we make a decision that vc-BACKEND-state can rely on FILE not
> having state `unregistered' (I'm not saying we should; it's just one
> option), that information should go into the Commentary at the top of
> vc.el (probably into the description of the `state' command), but...

So we are in agreement :-)

Of course, every relevant documentation must be up-to-date. Docstring,
commentary section, manual.

Personally, I believe a commentary section is a poor man's manual. Once
the information is in the manual, the commentary section is not needed
anymore. But this is nothing we need to worry about just now; let's
discuss it once a proper manual entry about vc exist.

Best regards, Michael.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]