[Doc-SIG] documenting Python constraints on types

[Fred L. Drake, Jr.]

Frederic Giacometti writes:
 > - Type documentation is not required in Python. Astonishingly
 >   enough, this is to be considered by 99,9% of the python
 >   programming population "Thou shallt not document argument and
 >   return types".

  I don't think that's quite it, though it certainly has an affect on
the interest in documenting the types.  Part of the lack of type
information is a matter of there not being a shared set of names for
abstract types that is also sufficient to be precise.  (For example:
What does it mean for an object to be a "mapping"?  Perhaps has_key()
is sufficient in one context, but get() and setdefault() are needed in
another.)  In practice, documenting the input types for highly
polymorphic code can be tedious, which certainly cuts down on the ease
of writing documentation which is useful, specific, and better than
just reading the sources.

[From the C/C++ example in the first document...]
 > void initXXX(void)
 > {
 >     PyObject* module, *docstring;
 >     module = Py_InitModule("XXX", XXX_methods);
 >     docstring = PyString_FromString("module short description
 > Public:
 >     - yyyType : TypeType -- yyy extenstion type
 >     ...
 > ");
 >     PyObject_SetAttrString(module, "__doc__", docstring);
 >     Py_DECREF(docstring);

  It's much easier to use Py_InitModule3():

void initXXX(void) {
    PyObject* module;

    module = Py_InitModule3("XXX", XXX_methods
                            "module short description
Public:
    - yyyType : TypeType -- yyy extenstion type
    ...
");


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Digital Creations