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

[Fernando Perez]

Travis Oliphant wrote:
> 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). 

Great!  I also hate writing docstrings in C, and this may significantly lower 
the barrier for users to contribute docstring patches.  It's a lot easier 
(esp. if a user is not a C programmer) to edit a plain python file full of 
"""strings""" than to dig into the C sources.

Since documentation is an area where users who don't feel comfortable with the 
internals can still make excellent contributions, I think this is an excellent 
development.

Cheers,

f