CodingGuidelines: Add a section on writing documentation
Provide a few examples on argument and option notation in usage strings and command synopses. Signed-off-by: Štěpán Němec <stepnem@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Štěpán Němec committed
Nov 4, 2010 at 18:12 UTC
c455bd8950e0e5593949b746ad96d1449bbbf9d5
1 file changed
+52
Documentation/CodingGuidelines
+52
@@ -139,3 +139,55 @@ For C programs:
139
140
- When we pass <string, length> pair to functions, we should try to
141
pass them in that order.
142
+
143
+Writing Documentation:
144
+
145
+ Every user-visible change should be reflected in the documentation.
146
+ The same general rule as for code applies -- imitate the existing
147
+ conventions. A few commented examples follow to provide reference
148
+ when writing or modifying command usage strings and synopsis sections
149
+ in the manual pages:
150
+
151
+ Placeholders are enclosed in angle brackets:
152
+ <file>
153
+ --sort=<key>
154
+ --abbrev[=<n>]
155
+
156
+ Possibility of multiple occurences is indicated by three dots:
157
+ <file>...
158
+ (One or more of <file>.)
159
+
160
+ Optional parts are enclosed in square brackets:
161
+ [<extra>]
162
+ (Zero or one <extra>.)
163
+
164
+ --exec-path[=<path>]
165
+ (Option with an optional argument. Note that the "=" is inside the
166
+ brackets.)
167
+
168
+ [<patch>...]
169
+ (Zero or more of <patch>. Note that the dots are inside, not
170
+ outside the brackets.)
171
+
172
+ Multiple alternatives are indicated with vertical bar:
173
+ [-q | --quiet]
174
+ [--utf8 | --no-utf8]
175
+
176
+ Parentheses are used for grouping:
177
+ [(<rev>|<range>)...]
178
+ (Any number of either <rev> or <range>. Parens are needed to make
179
+ it clear that "..." pertains to both <rev> and <range>.)
180
+
181
+ [(-p <parent>)...]
182
+ (Any number of option -p, each with one <parent> argument.)
183
+
184
+ git remote set-head <name> (-a | -d | <branch>)
185
+ (One and only one of "-a", "-d" or "<branch>" _must_ (no square
186
+ brackets) be provided.)
187
+
188
+ And a somewhat more contrived example:
189
+ --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
190
+ Here "=" is outside the brackets, because "--diff-filter=" is a
191
+ valid usage. "*" has its own pair of brackets, because it can
192
+ (optionally) be specified only when one or more of the letters is
193
+ also provided.