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
|
% Template for a library manual section.
% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
% ==== 1. ====
% The section prologue. Give the section a title and provide some
% meta-information. References to the module should use
% \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
% appropriate.
\section{\module{spam} ---
Short one-line descrition, for section title.}
% Choose one of these to specify the module module name. If there's
% an underscore in the name, use
% \declaremodule[modname]{...}{mod_name} instead.
%
\declaremodule{builtin}{spam} % standard library, in C
\declaremodule{standard}{spam} % standard library, in Python
\declaremodule{extension}{spam} % not standard, in C
\declaremodule{}{spam} % not standard, in Python
% These apply to all modules:
\moduleauthor{name}{email} % Author of the module code;
% omit if not known.
\sectionauthor{name}{email} % Author of the documentation.
% Leave at least one blank line after this, to simplify ad-hoc tools
% that are sometimes used to massage these files.
\modulesynopsis{This is a one-line descrition, for the chapter header.}
% ==== 2. ====
% Give a short overview of what the module does.
% If it is platform specific, mention this.
% Mention other important restrictions or general operating principles.
% For example:
The \module{spam} module defines operations for handling cans of Spam.
It knows the four generally available Spam varieties and understands
both can sizes.
Because spamification requires \UNIX{} process management, the module
is only available on genuine \UNIX{} systems.
% ==== 3. ====
% List the public functions defined by the module. Begin with a
% standard phrase. You may also list the exceptions and other data
% items defined in the module, insofar as they are important for the
% user.
The \module{spam} module defines the following functions:
% ---- 3.1. ----
% For each function, use a ``funcdesc'' block. This has exactly two
% parameters (each parameters is contained in a set of curly braces):
% the first parameter is the function name (this automatically
% generates an index entry); the second parameter is the function's
% argument list. If there are no arguments, use an empty pair of
% curly braces. If there is more than one argument, separate the
% arguments with backslash-comma. Optional parts of the parameter
% list are contained in \optional{...} (this generates a set of square
% brackets around its parameter). Arguments are automatically set in
% italics in the parameter list. Each argument should be mentioned at
% least once in the description; each usage (even inside \code{...})
% should be enclosed in \var{...}.
\begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
Open the file \var{filename} as a can of Spam. The optional
\var{mode} and \var{buffersize} arguments specify the read-write mode
(\code{'r'} (default) or \code{'w'}) and the buffer size (default:
system dependent).
\end{funcdesc}
% ---- 3.2. ----
% Data items are described using a ``datadesc'' block. This has only
% one parameter: the item's name.
\begin{datadesc}{cansize}
The default can size, in ounces. Legal values are 7 and 12. The
default varies per supermarket. This variable should not be changed
once the \function{open()} function has been called.
\end{datadesc}
% --- 3.3. ---
% Exceptions are described using a ``excdesc'' block. This has only
% one parameter: the exception name.
\begin{excdesc}{error}
Exception raised when an operation fails for a Spam specific reason.
The exception argument is a string describing the reason of the
failure.
\end{excdesc}
% ---- 3.4. ----
% Other standard environments:
%
% classdesc - Python classes; same arguments are funcdesc
% methoddesc - methods, like funcdesc but has an optional parameter
% to give the type name: \begin{methoddesc}[mytype]{name}{args}
% By default, the type name will be the name of the
% last class defined using classdesc. The type name
% is required if the type is implemented in C (because
% there's no classdesc) or if the class isn't directly
% documented (if it's private).
% memberdesc - data members, like datadesc, but with an optional
% type name like methoddesc.
% ==== 4. ====
% Now is probably a good time for a complete example. (Alternatively,
% an example giving the flavor of the module may be given before the
% detailed list of functions.)
Example:
\begin{verbatim}
>>> import spam
>>> can = spam.open('/etc/passwd')
>>> can.empty()
>>> can.close()
\end{verbatim}
% Note that there is no trailing ">>> " prompt shown.
% ==== 5. ====
% If your module defines new object types (for a built-in module) or
% classes (for a module written in Python), you should list the
% methods and instance variables (if any) of each type or class in a
% separate subsection.
\subsection{Spam Objects}
\label{spam-objects}
% This label is generally useful for referencing this section, but is
% also used to give a filename when generating HTML.
Spam objects, as returned by \function{open()} above, have the
following methods:
\begin{methoddesc}[spam]{empty}{}
Empty the can into the trash.
\end{methoddesc}
|
