Feature #957

Investigate automatic generation of meaningful docstring for PythonAPI

Added by pospelov over 5 years ago. Updated almost 5 years ago.

Status:ArchivedStart date:11 Feb 2015
Priority:NormalDue date:
Assignee:pospelov% Done:

0%

Category:-
Target version:Sprint 27

Description

The goal is to provide meaningful docstring for BornAgain classes and methods
  • either through boost-python machinery, if possible
  • or by patching docstring directly in bornagain.py
  • Is it possible to use xml-tree generated by Doxygen for this automatic generation?
  • See also #945 (PythonAPI in Drupal)

Some links:
http://stackoverflow.com/questions/15625065/define-a-boostfunction-with-a-docstring-boostpython
http://stackoverflow.com/questions/6114462/how-to-override-the-automatically-created-docstring-data-for-boostpython

History

#1 Updated by pospelov over 5 years ago

  • Description updated (diff)

#2 Updated by pospelov about 5 years ago

  • Status changed from New to Sprint
  • Target version set to Sprint 27

#3 Updated by pospelov about 5 years ago

  • Assignee set to pospelov

#4 Updated by pospelov about 5 years ago

  • Status changed from Sprint to Resolved

Summary:

New utils_docstring.py from python-bindings now parses C++ code for Doxygen comments and tries to form nicely looking Python docstring.

From C++ code

    //! @brief Cone constructor
    //! @param radius of Cone's base
    //! @param height of Cone
    //! @param angle in radians between base and facet
    FormFactorCone(double radius, double height,  double alpha);

it will generate docstring which from IPython console looks like

    __init__( (object)arg1, (float)radius, (float)height, (float)alpha) -> None :
        Cone constructor.

       :Parameters:
         - 'radius' - of Cone's base
         - 'height' - of Cone
         - 'angle' - in radians between base and facet

*Current limitations

  • One have to write doxygen comments more carefully. In example above one had to write
        //! @param radius Radius of Cone's base.
    
  • Parameter description can't occupy more than one line
  • @brief statement can be multiline and it will still be parsed correctly (untill next '.' or '\at_sign'). However it is better to have brief statement short to not to make Python docstring too heavy.
  • Avoid Latex statements in your 'brief' directive
    Instead of
    
    //! @class FTDistribution2DCone
    //! @ingroup algorithms
    //! @brief 2 dimensional cone distribution in Fourier space
    //! corresponds \f$r=\sqrt{(\frac{x}{\omega_x})^2 + (\frac{y}{\omega_y})^2}\f$
    
    use
    
    //! @class FTDistribution2DCone
    //! @ingroup algorithms
    //! @brief 2 dimensional cone distribution in Fourier space.
    //! Corresponds \f$r=\sqrt{(\frac{x}{\omega_x})^2 + (\frac{y}{\omega_y})^2}\f$
    
    I.e. put all Latex magic after the dot, to make brief statement really brief.
    
  • Unfortunately, this automatically generated user docstring doesn't work for virtual methods. Seems that it is a subject to investigate in the future (if we decide that we can afford this).
    It means that for Layer.setThickness (which is virtual) the docstring will look like
        setThickness( (Layer)arg1, (float)thickness) -> None
    
        setThickness( (Layer)arg1, (float)thickness) -> None
    

Please note that there is no user docstring here. And Boost docstring is duplicated. While for ParticleLayout.addParticle

addParticle(...) unbound libBornAgainCore.ParticleLayout method
    addParticle( (ParticleLayout)arg1, (IParticle)particle, (IRotation)rotation [, (float)depth=0.0 [, (float)abundance=1.0]]) -> None :
        Adds generic particle.

    addParticle( (ParticleLayout)arg1, (IParticle)particle [, (float)depth=0.0 [, (float)abundance=1.0]]) -> None :
        Adds particle without rotation.

  • And the last, but not least. Python's help function for big objects like help(FormFactorCone) is pretty useless. It produces to much output (including all our inheritanceship).

Besides that, now it is better than before. So I mark an issue as resolved.

#5 Updated by pospelov almost 5 years ago

  • Status changed from Resolved to Archived

Also available in: Atom PDF