From 1d8fb2d89478b461dcddaac16880886b14fd1977 Mon Sep 17 00:00:00 2001
From: Guido van Rossum <guido@python.org>
Date: Sun, 28 Jun 1998 16:54:49 +0000
Subject: Added doc strings.

---
 Modules/selectmodule.c | 32 +++++++++++++++++++--
 Modules/signalmodule.c | 76 ++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 98 insertions(+), 10 deletions(-)

diff --git a/Modules/selectmodule.c b/Modules/selectmodule.c
index be0c604..dc3b521 100644
--- a/Modules/selectmodule.c
+++ b/Modules/selectmodule.c
@@ -314,18 +314,46 @@ select_select(self, args)
 	return ret;
 }
 
+static char select_doc[] =
+"select(rlist, wlist, xlist[, timeout]) -> (rlist, wlist, xlist)\n\
+\n\
+Wait until one or more file descriptors are ready for some kind of I/O.\n\
+The first three arguments are lists of file descriptors to be waited for:\n\
+rlist -- wait until ready for reading\n\
+wlist -- wait until ready for writing\n\
+xlist -- wait for an ``exceptional condition''\n\
+If only one kind of condition is required, pass [] for the other lists.\n\
+A file descriptor is either a socket or file object, or a small integer\n\
+gotten from a fileno() method call on one of those.\n\
+\n\
+The optional 4th argument specifies a timeout in seconds; it may be\n\
+a floating point number to specify fractions of seconds.  If it is absent\n\
+or None, the call will never time out.\n\
+\n\
+The return value is a tuple of three lists corresponding to the first three\n\
+arguments; each contains the subset of the corresponding file descriptors\n\
+that are ready.\n\
+\n\
+*** IMPORTANT NOTICE ***\n\
+On Windows, only sockets are supported; on Unix, all file descriptors.";
+
 
 static PyMethodDef select_methods[] = {
-    {"select",	select_select, 1},
+    {"select",	select_select, 1, select_doc},
     {0,  	0},			     /* sentinel */
 };
 
+static char module_doc[] =
+"This module supports asynchronous I/O on multiple file descriptors.\n\
+\n\
+*** IMPORTANT NOTICE ***\n\
+On Windows, only sockets are supported; on Unix, all file descriptors.";
 
 void
 initselect()
 {
 	PyObject *m, *d;
-	m = Py_InitModule("select", select_methods);
+	m = Py_InitModule3("select", select_methods, module_doc);
 	d = PyModule_GetDict(m);
 	SelectError = PyErr_NewException("select.error", NULL, NULL);
 	PyDict_SetItemString(d, "error", SelectError);
diff --git a/Modules/signalmodule.c b/Modules/signalmodule.c
index bb7ac35..2c8d844 100644
--- a/Modules/signalmodule.c
+++ b/Modules/signalmodule.c
@@ -122,6 +122,12 @@ signal_default_int_handler(self, arg)
 	return NULL;
 }
 
+static char default_int_handler_doc[] =
+"default_int_handler(...)\n\
+\n\
+The default handler for SIGINT instated by Python.\n\
+It raises KeyboardInterrupt.";
+
 
 static RETSIGTYPE
 signal_handler(sig_num)
@@ -164,6 +170,11 @@ signal_alarm(self, args)
 	/* alarm() returns the number of seconds remaining */
 	return PyInt_FromLong(alarm(t));
 }
+
+static char alarm_doc[] =
+"alarm(seconds)\n\
+\n\
+Arrange for SIGALRM to arrive after the given number of seconds."
 #endif
 
 #ifdef HAVE_PAUSE
@@ -187,6 +198,11 @@ signal_pause(self, args)
 	Py_INCREF(Py_None);
 	return Py_None;
 }
+static char pause_doc[] =
+"pause()
+
+Wait until a signal arrives.";
+
 #endif
 
 
@@ -235,9 +251,20 @@ signal_signal(self, args)
 	return old_handler;
 }
 
+static char signal_doc[] =
+"signal(sig, action) -> action\n\
+\n\
+Set the action for the given signal.  The action can be SIG_DFL,\n\
+SIG_IGN, or a callable Python object.  The previous action is\n\
+returned.  See getsignal() for possible return values.\n\
+\n\
+*** IMPORTANT NOTICE ***\n\
+A signal handler function is called with two arguments:\n\
+the first is the signal number, the second is the interrupted stack frame.";
+
 
 static PyObject *
-signal_get_signal(self, args)
+signal_getsignal(self, args)
 	PyObject *self; /* Not used */
 	PyObject *args;
 {
@@ -255,24 +282,57 @@ signal_get_signal(self, args)
 	return old_handler;
 }
 
+static char getsignal_doc[] =
+"getsignal(sig) -> action\n\
+\n\
+Return the current action for the given signal.  The return value can be:\n\
+SIG_IGN -- if the signal is being ignored\n\
+SIG_DFL -- if the default action for the signal is in effect\n\
+None -- if an unknown handler is in effect\n\
+anything else -- the callable Python object used as a handler\n\
+";
 
 
 /* List of functions defined in the module */
 static PyMethodDef signal_methods[] = {
 #ifdef HAVE_ALARM
-	{"alarm",	        signal_alarm},
+	{"alarm",	        signal_alarm, 0, alarm_doc},
 #endif
-	{"signal",	        signal_signal},
-	{"getsignal",	        signal_get_signal},
+	{"signal",	        signal_signal, 0, signal_doc},
+	{"getsignal",	        signal_getsignal, 0, getsignal_doc},
 #ifdef HAVE_PAUSE
-	{"pause",	        signal_pause},
+	{"pause",	        signal_pause, 0, pause_doc},
 #endif
-	{"default_int_handler", signal_default_int_handler},
-	{NULL,		NULL}		/* sentinel */
+	{"default_int_handler", signal_default_int_handler, 0,
+				default_int_handler_doc},
+	{NULL,			NULL}		/* sentinel */
 };
 
 
 
+static char module_doc[] =
+"This module provides mechanisms to use signal handlers in Python.\n\
+\n\
+Functions:\n\
+\n\
+alarm() -- cause SIGALRM after a specified time [Unix only]\n\
+signal() -- set the action for a given signal\n\
+getsignal() -- get the signal action for a given signal\n\
+pause() -- wait until a signal arrives [Unix only]\n\
+default_int_handler() -- default SIGINT handler\n\
+\n\
+Constants:\n\
+\n\
+SIG_DFL -- used to refer to the system default handler\n\
+SIG_IGN -- used to ignore the signal\n\
+NSIG -- number of defined signals\n\
+\n\
+SIGINT, SIGTERM, etc. -- signal numbers\n\
+\n\
+*** IMPORTANT NOTICE ***\n\
+A signal handler function is called with two arguments:\n\
+the first is the signal number, the second is the interrupted stack frame.";
+
 void
 initsignal()
 {
@@ -285,7 +345,7 @@ initsignal()
 #endif
 
 	/* Create the module and add the functions */
-	m = Py_InitModule("signal", signal_methods);
+	m = Py_InitModule3("signal", signal_methods, module_doc);
 
 	/* Add some symbolic constants to the module */
 	d = PyModule_GetDict(m);
-- 
cgit v0.12

