Doc/libtemplate.tex

   1 % Template for a library manual section.
   2 % PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
   3
   4
   5 % ==== 1. ====
   6 % Choose one of the following section headers and index entries;
   7 % \section generates the section header,
   8 % \bimodindex or \stmodindex generates an index entry for this
   9 % module.  Note that these should only be used for the defining entry
  10 % for the module.  Other references to the module should use
  11 % \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
  12 % appropriate.  (Just prepend "ref" to the csname of the \*modindex
  13 % macro used in the module definition.)
  14 %
  15 % The \label{module-spam} line is for the \seealso command.
  16
  17 \section{Built-in Module \module{spam}} % If implemented in C, in
  18 \bimodindex{spam}                       % standard library
  19
  20 \section{Standard Module \module{spam}} % If implemented in Python, in
  21 \stmodindex{spam}                       % standard library
  22
  23 \section{Extension Module \module{spam}}% If implemented in C, but not
  24 \exmodindex{spam}                       % in standard library
  25
  26 \section{Module \module{spam}}          % If implemented in Python, but not
  27 \modindex{spam}                         % in standard library
  28
  29 \label{module-spam}
  30
  31 % ==== 2. ====
  32 % Give a short overview of what the module does.
  33 % If it is platform specific, mention this.
  34 % Mention other important restrictions or general operating principles.
  35 % For example:
  36
  37 The \module{spam} module defines operations for handling cans of Spam.
  38 It knows the four generally available Spam varieties and understands
  39 both can sizes.
  40
  41 Because spamification requires \UNIX{} process management, the module
  42 is only available on genuine \UNIX{} systems.
  43
  44
  45 % ==== 3. ====
  46 % List the public functions defined by the module.  Begin with a
  47 % standard phrase.  You may also list the exceptions and other data
  48 % items defined in the module, insofar as they are important for the
  49 % user.
  50
  51 The \module{spam} module defines the following functions:
  52
  53 % ---- 3.1. ----
  54 % For each function, use a ``funcdesc'' block.  This has exactly two
  55 % parameters (each parameters is contained in a set of curly braces):
  56 % the first parameter is the function name (this automatically
  57 % generates an index entry); the second parameter is the function's
  58 % argument list.  If there are no arguments, use an empty pair of
  59 % curly braces.  If there is more than one argument, separate the
  60 % arguments with backslash-comma.  Optional parts of the parameter
  61 % list are contained in \optional{...} (this generates a set of square
  62 % brackets around its parameter).  Arguments are automatically set in
  63 % italics in the parameter list.  Each argument should be mentioned at
  64 % least once in the description; each usage (even inside \code{...})
  65 % should be enclosed in \var{...}.
  66
  67 \begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
  68 Open the file \var{filename} as a can of Spam.  The optional
  69 \var{mode} and \var{buffersize} arguments specify the read-write mode
  70 (\code{'r'} (default) or \code{'w'}) and the buffer size (default:
  71 system dependent).
  72 \end{funcdesc}
  73
  74 % ---- 3.2. ----
  75 % Data items are described using a ``datadesc'' block.  This has only
  76 % one parameter: the item's name.
  77
  78 \begin{datadesc}{cansize}
  79 The default can size, in ounces.  Legal values are 7 and 12.  The
  80 default varies per supermarket.  This variable should not be changed
  81 once the \function{open()} function has been called.
  82 \end{datadesc}
  83
  84 % --- 3.3. ---
  85 % Exceptions are described using a ``excdesc'' block.  This has only
  86 % one parameter: the exception name.
  87
  88 \begin{excdesc}{error}
  89 Exception raised when an operation fails for a Spam specific reason.
  90 The exception argument is a string describing the reason of the
  91 failure.
  92 \end{excdesc}
  93
  94 % ---- 3.4. ----
  95 % Other standard environments:
  96 %
  97 %  classdesc    - Python classes; same arguments are funcdesc
  98 %  methoddesc   - methods, like funcdesc but has an optional parameter
  99 %                 to give the type name: \begin{methoddesc}[mytype]{name}{args}
 100 %                 By default, the type name will be the name of the
 101 %                 last class defined using classdesc.  The type name
 102 %                 is required if the type is implemented in C (because
 103 %                 there's no classdesc) or if the class isn't directly
 104 %                 documented (if it's private).
 105 %  memberdesc   - data members, like datadesc, but with an optional
 106 %                 type name like methoddesc.
 107
 108
 109 % ==== 4. ====
 110 % Now is probably a good time for a complete example.  (Alternatively,
 111 % an example giving the flavor of the module may be given before the
 112 % detailed list of functions.)
 113
 114 Example:
 115
 116 \begin{verbatim}
 117 >>> import spam
 118 >>> can = spam.open('/etc/passwd')
 119 >>> can.empty()
 120 >>> can.close()
 121 \end{verbatim}
 122 % Note that there is no trailing ">>> " prompt shown.
 123
 124 % ==== 5. ====
 125 % If your module defines new object types (for a built-in module) or
 126 % classes (for a module written in Python), you should list the
 127 % methods and instance variables (if any) of each type or class in a
 128 % separate subsection.
 129
 130 \subsection{Spam Objects}
 131 \label{spam-objects}
 132 % This label is generally useful for referencing this section, but is
 133 % also used to give a filename when generating HTML.
 134
 135 Spam objects, as returned by \function{open()} above, have the
 136 following methods:
 137
 138 \begin{methoddesc}[spam]{empty}{}
 139 Empty the can into the trash.
 140 \end{methoddesc}