From 1d8fb2d89478b461dcddaac16880886b14fd1977 Mon Sep 17 00:00:00 2001 From: Guido van Rossum 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