[minion-cvs] Flesh out inline documentation

[nickm@seul.org (Nick Mathewson)]

Update of /home/minion/cvsroot/src/minion/src
In directory moria.mit.edu:/tmp/cvs-serv14411/src

Modified Files:
	crypt.c fec.c 
Log Message:
Flesh out inline documentation

Index: crypt.c
===================================================================
RCS file: /home/minion/cvsroot/src/minion/src/crypt.c,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -d -r1.28 -r1.29
--- crypt.c	21 Aug 2003 21:32:30 -0000	1.28
+++ crypt.c	25 Aug 2003 21:05:34 -0000	1.29
@@ -292,7 +292,8 @@
 #ifdef MS_WINDOWS
 const char mm_win32_openssl_seed__doc__[]=
   "openssl_seed_win32()\n\n"
-  "DOCDOC\n";
+  "Windows-only function: seed OpenSSL's random number generator baswed on\n"
+  "the current contents of the screen.\n";
 
 PyObject *
 mm_win32_openssl_seed(PyObject *self, PyObject *args, PyObject *kwdict)
@@ -311,10 +312,13 @@
         return Py_None;
 }
 
-/* DOCDOC */
+/* Flag: set to true if the variable 'provider' has been set. */
 static int provider_set = 0;
+/* A global handle to a crypto context. */
 static HCRYPTPROV provider;
 
+/* Helper method: return a handle for a Windows Crypto API crypto provider,
+ * initializing it if necessary. */
 static HCRYPTPROV getProvider()
 {
         if (provider_set)
@@ -343,7 +347,8 @@
 
 const char mm_win32_get_random_bytes__doc__[]=
   "win32_get_random_bytes(n)\n\n"
-  "DOCDOC";
+  "Return n random bytes, using Windows's internal supposedly secure random\n"
+  "number generator.  \n";
 
 PyObject *
 mm_win32_get_random_bytes(PyObject *self, PyObject *args, PyObject *kwdict)
@@ -392,12 +397,13 @@
 #endif
 
 const char mm_openssl_rand__doc__[]=
-  "DOCDOC\n";
+  "openssl_rand(n)\n\n"
+  "Return n random bytes from OpenSSL's random number generator.\n";
 
 PyObject *
 mm_openssl_rand(PyObject *self, PyObject *args, PyObject *kwdict)
 {
-        static char *kwlist[] = { "bytes", NULL };
+        static char *kwlist[] = { "n", NULL };
         int bytes;
         PyObject *result;
         int r;
@@ -407,7 +413,7 @@
                 return NULL;
 
         if (bytes < 0) {
-                TYPE_ERR("bytes must be >= 0");
+                TYPE_ERR("n must be >= 0");
         }
 
         if (!(result = PyString_FromStringAndSize(NULL,bytes))) {

Index: fec.c
===================================================================
RCS file: /home/minion/cvsroot/src/minion/src/fec.c,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- fec.c	21 Aug 2003 21:32:30 -0000	1.9
+++ fec.c	25 Aug 2003 21:05:35 -0000	1.10
@@ -780,7 +780,7 @@
     return 0;
 }
 
-/* ======= PYTHON INTERFACE ====== */
+/* ======= ORIGINAL FEC CODE ENDS; PYTHON INTERFACE BEGINS ====== */
 
 char mm_FECError__doc__[] =
   "mixminion._minionlib.FECError\n\n"
@@ -797,7 +797,10 @@
 
 /* **************** */
 
-const char mm_FEC_generate__doc__[] = "DOCDOC";
+const char mm_FEC_generate__doc__[] = 
+ "fec_generate(k,n)\n\n"
+ "Return a FEC object to implement k-out-of-n erasure correcting codes, for\n"
+ "the provided values of k and n.\n";
 
 PyObject *
 mm_FEC_generate(PyObject *self, PyObject *args, PyObject *kwargs)
@@ -840,7 +843,9 @@
         PyObject_DEL(self);
 }
 
-static const char mm_FEC_getParameters__doc__[] = "DOCDOC";
+static const char mm_FEC_getParameters__doc__[] = 
+ "fec.getParameters() -> (k,n)\n\n"
+ "Return a 2-tuple of the k and n parameters for this FEC object.\n";
 
 static PyObject*
 mm_FEC_getParameters(PyObject *self, PyObject *args, PyObject *kwargs)
@@ -855,7 +860,11 @@
         return Py_BuildValue("ii", fec->k, fec->n);
 }
 
-static const char mm_FEC_encode__doc__[] = "DOCDOC";
+static const char mm_FEC_encode__doc__[] = 
+"fec.encode(idx,[blocks...])\n\n"
+"Encode a single block of FEC-encoded data.  'idx' is the index of the block\n"
+"to return (0<=idx<N), and 'blocks' is a list of K strings of equal length,\n"
+"containing the original string to encode.";
 
 static PyObject *
 mm_FEC_encode(PyObject *self, PyObject *args, PyObject *kwargs)
@@ -952,7 +961,13 @@
 	return NULL;
 }
 
-static const char mm_FEC_decode__doc__[] = "DOCDOC";
+static const char mm_FEC_decode__doc__[] = 
+ "fec.decode([ (idx1,block1), (idx2, block2), ...])\n\n"
+ "Recover a FEC-encoded string.  This methods expects as input a list of\n"
+ "2-tuples, each containing the index (0<=idx<=N) of an encoded block, and\n"
+ "the encoded block itself.  There must be exactly K elements in the list,\n"
+ "and their indices must be distinct.  Returns a list of K strings, which\n"
+ "when concatenated yields the original FEC-encoded string.\n";
 
 static PyObject *
 mm_FEC_decode(PyObject *self, PyObject *args, PyObject *kwargs)
@@ -1099,7 +1114,10 @@
         return Py_FindMethod(mm_FEC_methods, self, name);
 }
 
-static const char mm_FEC_Type__doc__[] = "DOCDOC";
+static const char mm_FEC_Type__doc__[] = 
+ "Type to implement forward error correction based on Vandermonde matrices.\n"
+ "The algorithm is from Luigi Rizzo; the underlying code is copyright\n"
+ "1997-1998 Luigi Rizzo; see fec.c for more information.\n";
 
 PyTypeObject mm_FEC_Type = {
 	PyObject_HEAD_INIT(/*&PyType_Type*/ 0)