[Numpy-svn] r3738 - trunk/numpy/core/code_generators

[numpy-svn at scipy.org]

Author: cookedm
Date: 2007-05-10 12:23:52 -0500 (Thu, 10 May 2007)
New Revision: 3738

Modified:
   trunk/numpy/core/code_generators/genapi.py
Log:
Add docstrings to numpy/core/code_generators/genapi.py


Modified: trunk/numpy/core/code_generators/genapi.py
===================================================================
--- trunk/numpy/core/code_generators/genapi.py	2007-05-09 16:27:06 UTC (rev 3737)
+++ trunk/numpy/core/code_generators/genapi.py	2007-05-10 17:23:52 UTC (rev 3738)
@@ -1,3 +1,10 @@
+"""
+Get API information encoded in C files.
+
+See ``find_function`` for how functions should be formatted, and
+``read_order`` for how the order of the functions should be
+specified.
+"""
 import sys, os, re
 import md5
 import textwrap
@@ -2,2 +9,5 @@
 
+__docformat__ = 'restructuredtext'
+
+# The files under src/ that are scanned for API functions
 API_FILES = ['arraymethods.c',
@@ -128,6 +138,27 @@
 
 
 def find_functions(filename, tag='API'):
+    """
+    Scan the file, looking for tagged functions.
+
+    Assuming ``tag=='API'``, a tagged function looks like::
+
+        /*API*/
+        static returntype*
+        function_name(argtype1 arg1, argtype2 arg2)
+        {
+        }
+
+    where the return type must be on a separate line, the function
+    name must start the line, and the opening ``{`` must start the line.
+
+    An optional documentation comment in ReST format may follow the tag,
+    as in::
+
+        /*API
+          This function does foo...
+         */
+    """
     fo = open(filename, 'r')
     functions = []
     return_type = None
@@ -191,6 +222,11 @@
     return functions
 
 def read_order(order_file):
+    """
+    Read the order of the API functions from a file.
+
+    Comments can be put on lines starting with #
+    """
     fo = open(order_file, 'r')
     order = {}
     i = 0