Add docstrings to Python interface via SWIG

[moschmdt]

At the moment the generated Python SML interface file does not contain the doxygen comments.

Is it possible to add the docstrings via the %feature("autodoc", ...) line, e.g. in the SWIG Python file?

[scijones]

I'll be honest -- I'm not familiar with this part of the code, but our software engineer is coming online soon (~weeks) and I'll run this by him.

[garfieldnate]

I think this is a great idea! I think the directives go in the CPP file. We would probably need to iterate on the actual documentation a bit, and experiment with the auto doc settings to get what we want.

This feature is supported for Python and Ruby only. Not sure about how the generated docs look for Java and the others.

[moschmdt]

I think this might also greatly benefit the Pysoarlib project, if this is still maintained?

[moschmdt]

@garfieldnate I got a working solution, but I think I do not have the permission to push a new branch and submit a PR.
It is sufficient to add the following line in the Python interface definition file:

%feature("autodoc","1"); 

I did already test it and it works, for example:

class ElementXML(object):
    r"""Proxy of C++ soarxml::ElementXML class."""

    thisown = property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc="The membership flag")
    __repr__ = _swig_repr

    @staticmethod
    def IsValidID(str):
        r"""IsValidID(char const * str) -> bool"""
        return _Python_sml_ClientInterface.ElementXML_IsValidID(str)

    def __init__(self, *args):
        r"""
        __init__(ElementXML self) -> ElementXML
        __init__(ElementXML self, ElementXML_Handle hXML) -> ElementXML
        """
        _Python_sml_ClientInterface.ElementXML_swiginit(self, _Python_sml_ClientInterface.new_ElementXML(*args))
    __swig_destroy__ = _Python_sml_ClientInterface.delete_ElementXML

[garfieldnate]

@moschmdt Cool, thanks! I think I'd go more verbose and use "3" instead of "1". The numpy-style parameter documentation is used by some tools.

You definitely have permissions to send a PR. Just click the little pencil at the top of the file display, edit it how you like, and GitHub should guide you through creating a fork and then sending a PR from the fork (you do not have permissions to edit the file directly; you always have to go through a fork).

[garfieldnate]

Revisiting this, I wanted to try adding in the actual doxygen comments contained in the C++ code using SWIG's -doxygen flag, but it only translates the comments contained in the one .i file, ignoring the comments elsewhere. This is a shame, as it would be very useful to have the full documentation available.