Doc/templates/module.tex

% Template for a library manual section.
% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE


% ==== 1. ====
% Choose one of the following section headers and index entries;
% \section{} generates the section header,
% \bimodindex{} or \stmodundex{} generates an index entry for this module

\section{Built-in Module \sectcode{spam}}	% If implemented in C
\bimodindex{spam}

\section{Standard module \sectcode{spam}}	% If implemented in Python
\stmodindex{spam}


% ==== 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 \code{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 \code{spam} module defines the following functions:

% ---- 3.1. ----
% Redefine the ``indexsubitem'' macro to point to this module
% (alternatively, you can put this at the top of the file):

\renewcommand{\indexsubitem}{(in module spam)}

% ---- 3.2. ----
% 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\, 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.3. ----
% 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 \code{open()} function has been called.
\end{datadesc}

% --- 3.4. ---
% 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.5. ----
% There is no standard block type for classes.  I generally use
% ``funcdesc'' blocks, since class instantiation looks very much like
% a function call.


% ==== 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}

% ==== 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.  It is important to redefine ``indexsubitem''
% for each subsection.

\subsection{Spam Objects}

Spam objects (returned by \code{open()} above) have the following
methods.

\renewcommand{\indexsubitem}{(spam method)}

\begin{funcdesc}{empty}{}
Empty the can into the trash.
\end{funcdesc}