Fill in a few holes in the "Very High Level" chapter.

freddrake · freddrake · commit 0041a94e7498 · 1999-04-29T04:20:46.000Z
diff --git a/Doc/api/api.tex b/Doc/api/api.tex
@@ -552,12 +552,25 @@ \chapter{The Very High Level Layer \label{veryhigh}}
 more detailed way with the interpreter.
 
 \begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
+  If \var{fp} refers to a file associated with an interactive device
+  (console or terminal input or \UNIX{} pseudo-terminal), return the
+  value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
+  result of \cfunction{PyRun_SimpleFile()}.  If \var{filename} is
+  \NULL{}, use \code{"???"} as the filename.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
+  Executes the Python source code from \var{command} in the
+  \module{__main__} module.  If \module{__main__} does not already
+  exist, it is created.  Returns \code{0} on success or \code{-1} if
+  an exception was raised.  If there was an error, there is no way to
+  get the exception information.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
+  Similar to \cfunction{PyRun_SimpleString()}, but the Python source
+  code is read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
@@ -568,24 +581,48 @@ \chapter{The Very High Level Layer \label{veryhigh}}
 
 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
                                                              int start}
+  Parse Python source code from \var{str} using the start token
+  \var{start}.  The result can be used to create a code object which
+  can be evaluated efficiently.  This is useful if a code fragment
+  must be evaluated many times.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
                                  char *filename, int start}
+  Similar to \cfunction{PyParser_SimpleParseString()}, but the Python
+  source code is read from \var{fp} instead of an in-memory string.
+  \var{filename} should be the name of the file.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
                                            PyObject *globals,
                                            PyObject *locals}
+  Execute Python source code from \var{str} in the context specified
+  by the dictionaries \var{globals} and \var{locals}.  The parameter
+  \var{start} specifies the start token that should be used to parse
+  the source code.
+
+  Returns the result of executing the code as a Python object, or
+  \NULL{} if an exception was raised.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
                                          int start, PyObject *globals,
                                          PyObject *locals}
+  Similar to \cfunction{PyRun_String()}, but the Python source code is 
+  read from \var{fp} instead of an in-memory string.  \var{filename}
+  should be the name of the file.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
                                                int start}
+  Parse and compile the Python source code in \var{str}, returning the 
+  resulting code object.  The start token is given by \var{start};
+  this can be used to constrain the code which can be compiled.  The
+  filename specified by \var{filename} is used to construct the code
+  object and may appear in tracebacks or \exception{SyntaxError}
+  exception messages.  This returns \NULL{} if the code cannot be
+  parsed or compiled.
 \end{cfuncdesc}
 
 
