[C++-sig] Boost.Python Feature Request

[Daniel Holth]

On Fri, 2004-01-16 at 08:41, Jenna Louis wrote:
> Are there any patches or plans to add the following features to
> Boost.Python/Pyste?
>  
> 1. A major usability problem of  Boost generated proxies is that IDEs
> are not able to show any details about the expected parameters. 
> Since Boost already knows everything about the function then it makes
> sense to at least make some information known about it via a docstring
> and then these tools can at least show that.

The last time I looked into this issue it turned out that pydoc (same as
help(foo) inside python) looks at code objects to automatically
determine the number and names of a method's parameters.  Only real
interpreted python code has these.

boost would have to generate bogus code objects to make help show
anything but f(...); a strategerie that kould be veery nasti at best, to
say nothing of overloaded methods.  So, just like builtin objects like
dict, we resort to providing our own docstrings as the last argument to
a .def(): "x.__cmp__(y) <==> cmp(x,y)" and so on.

On the other hand, if a meaningful docstring could be automatically
generated (perhaps from doxygen style docs embedded in the C++), that
would be awesome.  But really tricky.  It sounds like a job for Pyste
and gccxml.

Of course if the Python tracks the C++ closely enough, the C++ API
documentation is nearly as good - depending on how hard it is to switch
from your ide (vim!) to something like a web or class browser.

Here's an example of help illustrating introspectable and
non-introspectable methods:

    class BadStatusLine(HTTPException)
     |  Method resolution order:
     |      BadStatusLine
     |      HTTPException
     |      exceptions.Exception
     |
     |  Methods defined here:   
     |  __init__(self, line) 	# Python method
     |  Methods inherited from exceptions.Exception:
     |  __getitem__(...)	# Builtin (like Boost makes)
     |  __str__(...)