blob: 4afb56b251684f00aa35870407b8459ce8bf5fcf [file] [log] [blame]
Guido van Rossum51bbdfb1995-03-01 14:07:08 +00001% Template for a library manual section.
2% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
Guido van Rossum6a11eb41992-06-03 17:59:07 +00003
4
Guido van Rossum51bbdfb1995-03-01 14:07:08 +00005% ==== 1. ====
6% Choose one of the following section headers and index entries;
7% \section{} generates the section header,
8% \bimodindex{} or \stmodundex{} generates an index entry for this module
9
Guido van Rossum470be141995-03-17 16:07:09 +000010\section{Built-in Module \sectcode{spam}} % If implemented in C
Jack Jansenab71c3f1995-10-10 11:57:49 +000011\bimodindex{spam}
Guido van Rossum51bbdfb1995-03-01 14:07:08 +000012
13\section{Standard module \sectcode{spam}} % If implemented in Python
14\stmodindex{spam}
Guido van Rossum6a11eb41992-06-03 17:59:07 +000015
16
Guido van Rossum51bbdfb1995-03-01 14:07:08 +000017% ==== 2. ====
18% Give a short overview of what the module does.
19% If it is platform specific, mention this.
20% Mention other important restrictions or general operating principles.
21% For example:
22
23The \code{spam} module defines operations for handling cans of Spam.
24It knows the four generally available Spam varieties and understands
25both can sizes.
26
27Because spamification requires UNIX process management, the module is
28only available on genuine UNIX systems.
Guido van Rossum6a11eb41992-06-03 17:59:07 +000029
30
Guido van Rossum51bbdfb1995-03-01 14:07:08 +000031% ==== 3. ====
32% List the public functions defined by the module. Begin with a
33% standard phrase. You may also list the exceptions and other data
34% items defined in the module, insofar as they are important for the
35% user.
36
37The \code{spam} module defines the following functions:
38
39% ---- 3.1. ----
Guido van Rossumdc46c7f1995-03-01 15:38:16 +000040% Redefine the ``indexsubitem'' macro to point to this module
41% (alternatively, you can put this at the top of the file):
Guido van Rossum51bbdfb1995-03-01 14:07:08 +000042
43\renewcommand{\indexsubitem}{(in module spam)}
44
45% ---- 3.2. ----
46% For each function, use a ``funcdesc'' block. This has exactly two
47% parameters (each parameters is contained in a set of curly braces):
48% the first parameter is the function name (this automatically
49% generates an index entry); the second parameter is the function's
50% argument list. If there are no arguments, use an empty pair of
51% curly braces. If there is more than one argument, separate the
52% arguments with backslash-comma. Optional parts of the parameter
53% list are contained in \optional{...} (this generates a set of square
54% brackets around its parameter). Arguments are automatically set in
55% italics in the parameter list. Each argument should be mentioned at
56% least once in the description; each usage (even inside \code{...})
57% should be enclosed in \var{...}.
58
59\begin{funcdesc}{open}{filename\optional{\, mode\, buffersize}}
60Open the file \var{filename} as a can of Spam. The optional
61\var{mode} and \var{buffersize} arguments specify the read-write mode
62(\code{'r'} (default) or \code{'w'}) and the buffer size (default:
63system dependent).
64\end{funcdesc}
65
66% ---- 3.3. ----
67% Data items are described using a ``datadesc'' block. This has only
68% one parameter: the item's name.
69
70\begin{datadesc}{cansize}
71The default can size, in ounces. Legal values are 7 and 12. The
72default varies per supermarket. This variable should not be changed
73once the \code{open()} function has been called.
74\end{datadesc}
75
76% --- 3.4. ---
77% Exceptions are described using a ``excdesc'' block. This has only
78% one parameter: the exception name.
79
80\begin{excdesc}{error}
81Exception raised when an operation fails for a Spam specific reason.
82The exception argument is a string describing the reason of the
83failure.
84\end{excdesc}
85
86% ---- 3.5. ----
87% There is no standard block type for classes. I generally use
88% ``funcdesc'' blocks, since class instantiation looks very much like
89% a function call.
Guido van Rossum6a11eb41992-06-03 17:59:07 +000090
91
Guido van Rossum51bbdfb1995-03-01 14:07:08 +000092% ==== 4. ====
93% Now is probably a good time for a complete example. (Alternatively,
94% an example giving the flavor of the module may be given before the
95% detailed list of functions.)
Guido van Rossum6a11eb41992-06-03 17:59:07 +000096
Guido van Rossum51bbdfb1995-03-01 14:07:08 +000097Example:
Guido van Rossum6a11eb41992-06-03 17:59:07 +000098
Guido van Rossum51bbdfb1995-03-01 14:07:08 +000099\begin{verbatim}
100>>> import spam
101>>> can = spam.open('/etc/passwd')
102>>> can.empty()
103>>> can.close()
104\end{verbatim}
Guido van Rossum6a11eb41992-06-03 17:59:07 +0000105
Guido van Rossum51bbdfb1995-03-01 14:07:08 +0000106% ==== 5. ====
107% If your module defines new object types (for a built-in module) or
108% classes (for a module written in Python), you should list the
109% methods and instance variables (if any) of each type or class in a
110% separate subsection. It is important to redefine ``indexsubitem''
111% for each subsection.
112
Guido van Rossum470be141995-03-17 16:07:09 +0000113\subsection{Spam Objects}
Guido van Rossum51bbdfb1995-03-01 14:07:08 +0000114
115Spam objects (returned by \code{open()} above) have the following
116methods.
117
118\renewcommand{\indexsubitem}{(spam method)}
119
120\begin{funcdesc}{empty}{}
121Empty the can into the trash.
122\end{funcdesc}