@matheusbsbs / matheus-bagliano / commits / 6584fcc5c8

CodingGuidelines: update and clarify command-line conventions

Edit the section which explains how to create a good SYNOPSIS section for clarity and accuracy, it was mostly introduced in c455bd8950e (CodingGuidelines: Add a section on writing documentation, 2010-11-04): * Change "extra" example to "file", which now naturally follows from previous "<file>..." example (one or more) to "[<file>...]" (zero or more). * Explain how we prefer spacing around "[]()" tokens and "|" alternatives, this is not a new policy, but just codifies what's already the pattern in the most wide use in the documentation. Having a space around " | " for flags, but not for flag values is inconsistent, but this style guide codifies existing patterns. Grepping shows that we don't have any instance matching the second "Don't" example: git grep -E -h -o '=\([^)]+\)' -- builtin Documentation/ Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Ævar Arnfjörð Bjarmason committed Oct 13, 2022 at 17:38 UTC 6584fcc5c8ed2ed7e0785bcda3513a4bedb017ce

1 file changed +12 -2

Documentation/CodingGuidelines

+12 -2

@@ -650,8 +650,8 @@ Writing Documentation:

650 (One or more of <file>.)

651

652 Optional parts are enclosed in square brackets:

653 - [<extra>]

654 - (Zero or one <extra>.)

653 + [<file>...]

654 + (Zero or more of <file>.)

655

656 --exec-path[=<path>]

657 (Option with an optional argument. Note that the "=" is inside the

@@ -665,6 +665,16 @@ Writing Documentation:

665 [-q | --quiet]

666 [--utf8 | --no-utf8]

667

668 + Use spacing around "|" token(s), but not immediately after opening or

669 + before closing a [] or () pair:

670 + Do: [-q | --quiet]

671 + Don't: [-q|--quiet]

672 +

673 + Don't use spacing around "|" tokens when they're used to seperate the

674 + alternate arguments of an option:

675 + Do: --track[=(direct|inherit)]

676 + Don't: --track[=(direct | inherit)]

677 +

678 Parentheses are used for grouping:

679 [(<rev> | <range>)...]

680 (Any number of either <rev> or <range>. Parens are needed to make