1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
<html lang="en">
<head>
<title>Documentation Tips - Untitled</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Untitled">
<meta name="generator" content="makeinfo 4.11">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Tips-and-Standards.html#Tips-and-Standards" title="Tips and Standards">
<link rel="prev" href="Function-Headers.html#Function-Headers" title="Function Headers">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<p>
<a name="Documentation-Tips"></a>
Previous: <a rel="previous" accesskey="p" href="Function-Headers.html#Function-Headers">Function Headers</a>,
Up: <a rel="up" accesskey="u" href="Tips-and-Standards.html#Tips-and-Standards">Tips and Standards</a>
<hr>
</div>
<h3 class="section">C.5 Tips for Documentation Strings</h3>
<p>As noted above, documentation is typically in a commented header block
on an Octave function following the copyright statement. The help string
shown above is an unformatted string and will be displayed as is by
Octave. Here are some tips for the writing of documentation strings.
<ul>
<li>Every command, function, or variable intended for users to know about
should have a documentation string.
<li>An internal variable or subroutine of an Octave program might as well have
a documentation string.
<li>The first line of the documentation string should consist of one or two
complete sentences that stand on their own as a summary.
<p>The documentation string can have additional lines that expand on the
details of how to use the function or variable. The additional lines
should also be made up of complete sentences.
<li>For consistency, phrase the verb in the first sentence of a
documentation string as an infinitive with “to” omitted. For
instance, use “Return the frob of A and B.” in preference to “Returns
the frob of A and B.” Usually it looks good to do likewise for the
rest of the first paragraph. Subsequent paragraphs usually look better
if they have proper subjects.
<li>Write documentation strings in the active voice, not the passive, and in
the present tense, not the future. For instance, use “Return a list
containing A and B.” instead of “A list containing A and B will be
returned.”
<li>Avoid using the word “cause” (or its equivalents) unnecessarily.
Instead of, “Cause Octave to display text in boldface,” write just
“Display text in boldface.”
<li>Do not start or end a documentation string with whitespace.
<li>Format the documentation string so that it fits in an Emacs window on an
80-column screen. It is a good idea for most lines to be no wider than
60 characters.
<p>However, rather than simply filling the entire documentation string, you
can make it much more readable by choosing line breaks with care.
Use blank lines between topics if the documentation string is long.
<li><strong>Do not</strong> indent subsequent lines of a documentation string so
that the text is lined up in the source code with the text of the first
line. This looks nice in the source code, but looks bizarre when users
view the documentation. Remember that the indentation before the
starting double-quote is not part of the string!
<li>The documentation string for a variable that is a yes-or-no flag should
start with words such as “Nonzero means<small class="dots">...</small>”, to make it clear that
all nonzero values are equivalent and indicate explicitly what zero and
nonzero mean.
<li>When a function's documentation string mentions the value of an argument
of the function, use the argument name in capital letters as if it were
a name for that value. Thus, the documentation string of the operator
<code>/</code> refers to its second argument as ‘<samp><span class="samp">DIVISOR</span></samp>’, because the
actual argument name is <code>divisor</code>.
<p>Also use all caps for meta-syntactic variables, such as when you show
the decomposition of a list or vector into subunits, some of which may
vary.
</ul>
<p>Octave also allows extensive formatting of the help string of functions
using Texinfo. The effect on the online documentation is relatively
small, but makes the help string of functions conform to the help of
Octave's own functions. However, the effect on the appearance of printed
or online documentation will be greatly improved.
<p>The fundamental building block of Texinfo documentation strings is the
Texinfo-macro <code>@deftypefn</code>, which takes three arguments: The class
the function is in, its output arguments, and the function's
signature. Typical classes for functions include <code>Function File</code>
for standard Octave functions, and <code>Loadable Function</code> for
dynamically linked functions. A skeletal Texinfo documentation string
therefore looks like this
<pre class="example"> -*- texinfo -*-
@deftypefn{Function File} {@var{ret} =} fn (...)
@cindex index term
Help text in Texinfo format. Code samples should be marked
like @code{sample of code} and variables should be marked
as @var{variable}.
@seealso{fn2}
@end deftypefn
</pre>
<p>This help string must be commented in user functions, or in the help
string of the <code>DEFUN_DLD</code><!-- /@w --> macro for dynamically loadable
functions. The important aspects of the documentation string are
<dl>
<dt>-*- texinfo -*-<dd>This string signals Octave that the following text is in Texinfo format,
and should be the first part of any help string in Texinfo format.
<br><dt>@deftypefn{class} <small class="dots">...</small> @end deftypefn<dd>The entire help string should be enclosed within the block defined by
deftypefn.
<br><dt>@cindex index term<dd>This generates an index entry, and can be useful when the function is
included as part of a larger piece of documentation. It is ignored
within Octave's help viewer. Only one index term may appear per line
but multiple @cindex lines are valid if the function should be
filed under different terms.
<br><dt>@var{variable}<dd>All variables should be marked with this macro. The markup of variables
is then changed appropriately for display.
<br><dt>@code{sample of code}<dd>All samples of code should be marked with this macro for the same
reasons as the @var macro.
<br><dt>@seealso{function2}<dd>This is a comma separated list of function names that allows cross
referencing from one function documentation string to another.
</dl>
<p>Texinfo format has been designed to generate output for online viewing
with text terminals as well as generating high-quality printed output.
To these ends, Texinfo has commands which control the diversion of parts
of the document into a particular output processor. Three formats are
of importance: info, html and TeX. These are selected with
<pre class="example"> @ifinfo
Text area for info only
@end ifinfo
</pre>
<pre class="example"> @ifhtml
Text area for HTML only
@end ifhtml
</pre>
<pre class="example"> @tex
Text area for TeX only
@end tex
</pre>
<p>Note that often TeX output can be used in html documents and so often
the <code>@ifhtml</code> blocks are unnecessary. If no specific output
processor is chosen, by default, the text goes into all output
processors. It is usual to have the above blocks in pairs to allow the
same information to be conveyed in all output formats, but with a
different markup. Currently, most Octave documentation only makes a
distinction between TeX and all other formats. Therefore, the
following construct is seen repeatedly.
<pre class="example"> @tex
text for TeX only
@end tex
@ifnottex
text for info, HTML, plaintext
@end ifnottex
</pre>
<p>Another important feature of Texinfo that is often used in Octave help
strings is the <code>@example</code> environment. An example of its use is
<pre class="example"> @example
@group
@code{2 * 2}
@result{} 4
@end group
@end example
</pre>
<p>which produces
<pre class="example"> <code>2 * 2</code>
4
</pre>
<p>The <code>@group</code> block prevents the example from being split across a
page boundary, while the <code>@result{}</code> macro produces a right
arrow signifying the result of a command. If your example is larger than
20 lines it is better NOT to use grouping so that a reasonable page boundary
can be calculated.
<p>In many cases a function has multiple ways in which it can be called,
and the <code>@deftypefnx</code> macro can be used to give alternatives. For
example
<pre class="example"> -*- texinfo -*-
@deftypefn{Function File} {@var{a} =} fn (@var{x}, ...)
@deftypefnx{Function File} {@var{a} =} fn (@var{y}, ...)
Help text in Texinfo format.
@end deftypefn
</pre>
<p>Many complete examples of Texinfo documentation can be taken from the
help strings for the Octave functions themselves. A relatively complete
example of which is the <code>nchoosek</code> function. The Texinfo
documentation string for <code>nchoosek</code> is
<pre class="example"> -*- texinfo -*-
@deftypefn {Function File} {} nchoosek (@var{n}, @var{k})
Compute the binomial coefficient or all combinations of
@var{n}. If @var{n} is a scalar then, calculate the
binomial coefficient of @var{n} and @var{k}, defined as
@tex
$$
{n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
$$
@end tex
@ifnottex
@example
@group
/ \
| n | n (n-1) (n-2) ... (n-k+1)
| | = -------------------------
| k | k!
\ /
@end group
@end example
@end ifnottex
If @var{n} is a vector, this generates all combinations
of the elements of @var{n}, taken @var{k} at a time,
one row per combination. The resulting @var{c} has size
@code{[nchoosek (length (@var{n}),@var{k}), @var{k}]}.
@code{nchoosek} works only for non-negative integer arguments; use
@code{bincoeff} for non-integer scalar arguments and for using vector
arguments to compute many coefficients at once.
@seealso{bincoeff}
@end deftypefn
</pre>
<p>which demonstrates most of the concepts discussed above.
<!-- DO NOT EDIT! Generated automatically by munge-texi. -->
<!-- Copyright (C) 2008, 2009 Jaroslav Hajek -->
<!-- This file is part of Octave. -->
<!-- Octave is free software; you can redistribute it and/or modify it -->
<!-- under the terms of the GNU General Public License as published by the -->
<!-- Free Software Foundation; either version 3 of the License, or (at -->
<!-- your option) any later version. -->
<!-- Octave is distributed in the hope that it will be useful, but WITHOUT -->
<!-- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -->
<!-- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -->
<!-- for more details. -->
<!-- You should have received a copy of the GNU General Public License -->
<!-- along with Octave; see the file COPYING. If not, see -->
<!-- <http://www.gnu.org/licenses/>. -->
</body></html>
|
