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

From: Štěpán Němec <stepnem@gmail.com>
Date: Oct 29, 2010, 11:54 UTC
Message-ID: <87wrp12p00.fsf@gmail.com>
In-Reply-To: <AANLkTimpJbuZAPfvVOedstV7=UiLiDMnDaYWQLVNQ+Yc@mail.gmail.com>

Mark Lodato <lodatom@gmail.com> writes:

Show 10 quoted lines

> On Sun, Oct 24, 2010 at 11:51 AM, Štěpán Němec <stepnem@gmail.com> wrote:
>> + 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>]]

Yeah, it's kind of an oddball, although I don't really find it confusing. I guess it might be useful in cases where you have a bigger number of "things", say 4 or more, where the brackets could get unwieldy.

But given that it's only used as {0,2} at the two places right now (disregarding occurences of "0{40}" in the documentation), I agree it might be better to get rid of it, although I don't feel strongly about it. Any other opinions?

Show 9 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]

Good point, will do.

Show 9 quoted lines

> 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]

I thought about this already when preparing the recent unification series, and came to the conclusion "no, there shouldn't". :-) As the examples you give show, the current usage is inconsistent, but given that it brings no semantic ambiguity, I don't think it is a problem. You could find more similar cosmetic inconsistencies and I don't think it makes much sense to mandate any rules for such things. (But again, I don't feel _too_ strongly about this either, so if more people think it's worth it, I can prepare a patch that unifies them and mention the preference in CodingGuidelines.)

> Otherwise, I think this patch looks good.

Thank you for the feedback!

Štěpán