Re: [Epydoc-devel] [C++-sig] Better introspection/apidoc extraction support?

[Hans M. <me...@in...>]

Hi Ralf!

Am Dienstag, 22. Mai 2007 19:14:42 schrieb Ralf W. Grosse-Kunstleve:
> Sorry, this looks like more work than I'm able to squeeze in. I was hoping
> for a well-established, time-tested API, but it looks more like work in
> progress.

That's a pity, but I can understand it.  OTOH, I don't think there is much 
progress ATM, as long as PEP 362 is not implemented.  (Is there a reason you 
did not reply to my later post where I mentioned 
http://www.python.org/dev/peps/pep-0362/ - I just want to make sure you saw 
it.)

I indeed wrote a parser for the C++ signatures for epydoc, but it is quite 
complicated since I have to
- parse arbitrary C++ types (templates with argument literals,
  namespaces, ...), which made me hack together a rather largish
  pyparsing-based parser (and as you know, writing a C++ parser is not what
  you wanna do..)
- parse arbitrary Python __repr__ output for the default arguments.
  Again, that is not doable with just regular expressions, also the __repr__
  can be basically anything, so it cannot be 100% safe.

It would be much better if there was an API to extract argument names and 
default values.

> The current docstring support isn't all that complicated. Look in
> boost/libs/python/src/object/function.cpp, mainly function::signature().

When using epydoc, I noticed that the resulting docstrings are no valid reST 
anymore if the original docstring does not end with a \n:

"""foo bar
C++ signature:
   test(void) -> void"""

However, this would be a valid description list:

"""foo bar

C++ signature:
   test(void) -> void"""

Would it make sense to just add two \n instead of one in
libs/python/src/object/function.cpp:510?

Or look at the attached patch, which also cares about docstrings to which a \n 
has manually been appended for boost 1.34.0beta + epydoc support.

That does not yet lead to a very pretty output, but it is a minimal change 
that makes epydoc w/ reST work at least, without further modifications.

-- 
Ciao, /  /
     /--/
    /  / ANS