Re: [PATCH] CodingGuidelines: Add a section on writing documentation

From: Mark Lodato <lodatom@gmail.com>
Date: Oct 29, 2010, 02:56 UTC
Message-ID: <AANLkTimpJbuZAPfvVOedstV7=UiLiDMnDaYWQLVNQ+Yc@mail.gmail.com>
In-Reply-To: <20101024155121.GA9503@headley>

On Sun, Oct 24, 2010 at 11:51 AM, Štěpán Němec <stepnem@gmail.com> wrote:

> Provide a few examples on argument and option notation in usage strings
> and command synopses.

I think this is a great idea.

> + Specific number of occurences is indicated as follows:
> +   <commit>{0,2}
> +   (Up to two <commit>s.)

I suggest removing this notation - it is confusing and is only used by git-diff.txt and git-difftool.txt. We already have notation to serve this purpose:

    [<commit> [<commit>]]

Show 5 quoted lines

> + Parentheses are used for grouping, often combined with vertical bar
> + to indicate alternatives:
> +   [(<rev>|<range>)...]
> +   (Any number of either <rev> or <range>.  Parens are needed to make
> +   it clear that "..." pertains to both <rev> and <range>.)

You could also mention that parentheses are not needed if square
brackets will do:
    [-q | --quiet]

Also, should there be a standard for spacing and for whether the short or the long option comes first?

git-add.txt:
    [--patch | -p]
git-commit.txt:
    [-a | --interactive]
git-stash.txt:
    [-q|--quiet]

Otherwise, I think this patch looks good.