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