Re: [Swig-user] C++ documentation to Python docstrings

[Bob H. <bh...@co...>]

Thanks, William.  However, since I did not receive any immediate
feedback, I went ahead and wrote a Python script that scans SWIG
interface files for included C++ header files, creates mappings between
exposed classes/methods, extracts doxygen comments from C++ classes and
methods, and then injects them directly into the generated Python
wrapper file to their corresponding shadow versions.  It has become a
single automated build step, and works quite well for my needs.

For exampe, I can enter "help(Parameter)" in my Python environment, and
this doxygen comment in the C++ header:

    /// @class Parameter
    /// @brief Value management and evaluation
    ///
    /// The Parameter class serves as the container of the data types
used by Asgard.
    /// This base implementation stores and transports most of the base
types needed
    /// to make an application function.  In addition, it provides some
operator
    /// interfaces to make math and equation operations function on
parameters just
    /// as they would integral data types.
    [...]

displays directly to the user as:

    >>> Help on class Parameter in module PyAsgardLib:

    ... class Parameter(__builtin__.object)

    ... | Class: Parameter

    ... | Use: Value management and evaluation

    ... |

    ... | The Parameter class serves as the container of the data types
used by Asgard.

    ... | This base implementation stores and transports most of the
base types needed

    ... | to make an application function. In addition, it provides some
operator

    ... | interfaces to make math and equation operations function on
parameters just

    ... | as they would integral data types.

    [...]



William S Fulton wrote:
> Bob Hood wrote:
>> Has an elegant way yet been added to SWIG to extract C++ class
>> documentation (in the form of some type of comment) into a Python
>> docstring for the generated shadow class?  I've seen the doxy2swig.py
>> script, but I was wondering if anything had be implemented directly
>> within SWIG itself since that was created?
>>
> Doxygen comments can be extracted from the C++ headers to create
> Python docstrings. The work has been done in a separate branch:
>
> http://swig.svn.sourceforge.net/viewvc/swig/branches/gsoc2008-cherylfoil
>
> I'm not entirely sure what state it is in. If you look at it, please
> let us know on the swig-devel mailing list as I'd like to merge this
> work into trunk at some point.
>
> William
>

Render me gone,                       |||
Bob                                 ^(===)^
---------------------------------oOO--(_)--OOo---------------------------------
       The amount you paid for your vehicle does not determine the degree
               to which driving laws will apply to you.  Sorry.