Exhibit good form in C code: always provide docstrings in method tables, and

freddrake · freddrake · commit ef6373a4f67d · 2001-11-17T06:50:42.000Z
always fill in all slots of table entries.
Fixed a few minor markup errors.
diff --git a/Doc/ext/embedding.tex b/Doc/ext/embedding.tex
@@ -231,9 +231,10 @@ \section{Extending Embedded Python
     return Py_BuildValue("i", numargs);
 }
 
-static PyMethodDef EmbMethods[]={
-    {"numargs", emb_numargs, METH_VARARGS},
-    {NULL,      NULL}
+static PyMethodDef EmbMethods[] = {
+    {"numargs", emb_numargs, METH_VARARGS,
+     "Return the number of arguments received by the process."},
+    {NULL, NULL, 0, NULL}
 };
 \end{verbatim}
 
diff --git a/Doc/ext/extending.tex b/Doc/ext/extending.tex
@@ -215,7 +215,7 @@ \section{Intermezzo: Errors and Exceptions
 
 \begin{verbatim}
 void
-initspam()
+initspam(void)
 {
     PyObject *m, *d;
 
@@ -308,9 +308,10 @@ \section{The Module's Method Table and Initialization Function
 \begin{verbatim}
 static PyMethodDef SpamMethods[] = {
     ...
-    {"system",  spam_system, METH_VARARGS},
+    {"system",  spam_system, METH_VARARGS,
+     "Execute a shell command."},
     ...
-    {NULL,      NULL}        /* Sentinel */
+    {NULL, NULL, 0, NULL}        /* Sentinel */
 };
 \end{verbatim}
 
@@ -340,7 +341,7 @@ \section{The Module's Method Table and Initialization Function
 
 \begin{verbatim}
 void
-initspam()
+initspam(void)
 {
     (void) Py_InitModule("spam", SpamMethods);
 }
@@ -992,12 +993,13 @@ \section{Keyword Parameters for Extension Functions
      * only take two PyObject* parameters, and keywdarg_parrot() takes
      * three.
      */
-    {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS|METH_KEYWORDS},
-    {NULL,  NULL}   /* sentinel */
+    {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS|METH_KEYWORDS,
+     "Print a lovely skit to standard output."},
+    {NULL, NULL, 0, NULL}   /* sentinel */
 };
 
 void
-initkeywdarg()
+initkeywdarg(void)
 {
   /* Create the module and add the functions */
   Py_InitModule("keywdarg", keywdarg_methods);
@@ -1590,7 +1592,7 @@ \section{Providing a C API for an Extension Module
 
 \begin{verbatim}
 void
-initspam()
+initspam(void)
 {
     PyObject *m;
     static void *PySpam_API[PySpam_API_pointers];
@@ -1614,8 +1616,8 @@ \section{Providing a C API for an Extension Module
 }
 \end{verbatim}
 
-Note that \code{PySpam_API} is declared \code{static}; otherwise
-the pointer array would disappear when \code{initspam} terminates!
+Note that \code{PySpam_API} is declared \keyword{static}; otherwise
+the pointer array would disappear when \function{initspam()} terminates!
 
 The bulk of the work is in the header file \file{spammodule.h},
 which looks like this:
@@ -1679,7 +1681,7 @@ \section{Providing a C API for an Extension Module
 
 \begin{verbatim}
 void
-initclient()
+initclient(void)
 {
     PyObject *m;
 
diff --git a/Doc/ext/newtypes.tex b/Doc/ext/newtypes.tex
@@ -77,8 +77,9 @@ \section{The Basics
 };
 
 static PyMethodDef noddy_methods[] = {
-    { "new_noddy", noddy_new_noddy, METH_VARARGS },
-    {NULL, NULL}
+    {"new_noddy", noddy_new_noddy, METH_VARARGS,
+     "Create a new Noddy object."},
+    {NULL, NULL, 0, NULL}
 };
 
 DL_EXPORT(void)
@@ -581,9 +582,11 @@ \subsection{Attribute Management Functions}
 
 \begin{verbatim}
 static PyMethodDef newdatatype_methods[] = {
-    {"getSize", (PyCFunction)newdatatype_getSize, METH_VARARGS},
-    {"setSize", (PyCFunction)newdatatype_setSize, METH_VARARGS},
-    {NULL,      NULL}           /* sentinel */
+    {"getSize", (PyCFunction)newdatatype_getSize, METH_VARARGS,
+     "Return the current size."},
+    {"setSize", (PyCFunction)newdatatype_setSize, METH_VARARGS,
+     "Set the size."},
+    {NULL, NULL, 0, NULL}           /* sentinel */
 };
 
 static PyObject *
