vc docstrings

vc docstrings

[Miles Bader]

I notice `vc-next-action' has a docstring of the form:

   SHORT_DESCRIPTION

   For locking systems:
   ... LONG DESCRIPTION FOR LOCKING VCS

   For merging systems:
   ... LONG DESCRIPTION FOR MERGING VCS

Given that all commonly used source-control systems these days are
the "merging" type, shouldn't the section on "merging systems" be first?

Also, I think many users are probably only vaguely aware that there _is_
such a distinction (how many people these days have ever used RCS?), so
perhaps it would be a good idea to give a list of common systems of each
type directly in the comment.

E.g., change the "merging systems" header to:

   For merging systems (CVS, Subversion, Git, Bzr, Hg, Arch):

[Maybe similar comments apply to other vc-... commands too.]

Thanks,

-Miles

-- 
"Most attacks seem to take place at night, during a rainstorm, uphill,
 where four map sheets join."   -- Anon. British Officer in WW I

Re: vc docstrings

[Stefan Monnier]

> Given that all commonly used source-control systems these days are
> the "merging" type, shouldn't the section on "merging systems" be first?

Yes.  It may even present itself as "the way it works" and the locking
version only presented as an exception at the end.

> E.g., change the "merging systems" header to:
>    For merging systems (CVS, Subversion, Git, Bzr, Hg, Arch):
> [Maybe similar comments apply to other vc-... commands too.]

Better list the locking ones, it's less likely to change over time.


        Stefan