cpython/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 \stmodindex{} generates an index entry for this
% module.  Note that these should only be used for the defining entry
% for the module.  Other references to the module should use
% \refbimodindex{} or \refstmodindex{}.
% The \label{module-spam} line is for the \seealso{} command.

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

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

\label{module-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 \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. ----
% Redefine the ``indexsubitem'' macro to point to this module
% (alternatively, you can put this at the top of the file):

\setindexsubitem{(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 \function{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 \function{open()} above) have the following
methods.

\setindexsubitem{(spam method)}

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