Re: Docstrings and manuals

[Michael Albinus]

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.