[SciPy-dev] Alternative to Docstrings in C-code

[Travis Oliphant]

I want to let people know that I've started a little project to remove 
docstrings from c-code and place them in a python module that will 
dynamically add docstrings to builtin functions.  I don't know about 
you, but I hate writing docstrings in C-code.  It's much harder to get 
the formatting to look right, and it's much more painful than in 
Python.  Also, having all the docstrings in one place might actually 
make for a nice little reference. 

I don't know what kind of loading speed impact this will have (if any), 
so I'm proceeding cautiously.  Currently, there is a simple utitlity 
called add_docstring in the _compiled_base module that can add a 
docstring to a builtin-function-or-method object or a type object. It 
only works if the object does not already have a docstring (because once 
added the Python string is never released until Python exits). 

I've heard some things on blogs that convince me that (unfortunately) I 
need to reassure certain people that this is *not* some sneaky attempt 
to remove docstrings.  I'm actually trying to make them more convenient 
to add, update, and maintain.   I like docstrings as much as anybody.  I 
also like them to look good.

-Travis