Need Python documentation for Boost (C) objects

[demisjohn]

From @demisjohn on March 7, 2018 13:51

Currently, getting help() on a boost object (defined in C I think), does not show any useful user-written documentation on how to use the object.

Should add documentation to clarify how to use these objects.

Example of help( camfr.Section ), which should say something like

 __init__( self, first_pass_modes, second_pass_modes)

The line s = Section(all, 10, 40) means we use (2*10+1)^2 plane waves in the first stage, and refine it using 40 1D modes in each Slab during the second stage.

instead we get a cryptic:

>>> help(c.Section)
Help on class Section in module camfr._camfr:

class Section(MultiWaveguide)
 |  Method resolution order:
 |      Section
 |      MultiWaveguide
 |      Waveguide
 |      Boost.Python.instance
 |      __builtin__.object
 |  
 |  Methods defined here:
 |  
 |  __init__(...)
 |      __init__( (object)arg1, (Expression)arg2 [, (int)arg3 [, (int)arg4]]) -> None :
 |      
 |          C++ signature :
 |              void __init__(_object*,Expression {lvalue} [,int [,int]])
 |      
 |      __init__( (object)arg1, (Expression)arg2, (Expression)arg3 [, (int)arg4 [, (int)arg5]]) -> None :
 |      
 |          C++ signature :
 |              void __init__(_object*,Expression {lvalue},Expression {lvalue} [,int [,int]])
 |      
 |      __init__( (object)arg1, (Term)arg2) -> None :
 |      
 |          C++ signature :
 |              void __init__(_object*,Term)
 |  
 |  __reduce__ = <unnamed Boost.Python function>(...)
 |  
 |  disp(...)
 |      disp( (Section)arg1, (complex)arg2) -> complex :
 |      
 |          C++ signature :
 |              std::__1::complex<double> disp(Section {lvalue},std::__1::complex<double>)
 |  
 |  eps(...)
 |      eps( (Section)arg1, (Coord)arg2) -> complex :
 |      
 |          C++ signature :
 |              std::__1::complex<double> eps(Section {lvalue},Coord)
 |  
 |  height(...)
 |      height( (Section)arg1) -> float :
 |      
 |          C++ signature :
 |              double height(Section {lvalue})
 |  
 |  mode(...)
 |      mode( (Section)arg1, (int)arg2) -> SectionMode :
 |      
 |          C++ signature :
 |              SectionMode* mode(Section,int)
 |  
 |  mu(...)
 |      mu( (Section)arg1, (Coord)arg2) -> complex :
 |      
 |          C++ signature :
 |              std::__1::complex<double> mu(Section {lvalue},Coord)
 |  
 |  n(...)
 |      n( (Section)arg1, (Coord)arg2) -> complex :
 |      
 |          C++ signature :
 |              std::__1::complex<double> n(Section {lvalue},Coord)
 |  
 |  set_estimate(...)
 |      set_estimate( (Section)arg1, (complex)arg2) -> None :
 |      
 |          C++ signature :
 |              void set_estimate(Section {lvalue},std::__1::complex<double>)
 |  
 |  set_sorting(...)
 |      set_sorting( (Section)arg1, (Sort_type)arg2) -> None :
 |      
 |          C++ signature :
 |              void set_sorting(Section {lvalue},Sort_type)
 |  
 |  width(...)
 |      width( (Section)arg1) -> float :
 |      
 |          C++ signature :
 |              double width(Section {lvalue})
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  __instance_size__ = 120
 |  
 |  ----------------------------------------------------------------------

Copied from original issue: #8

[demisjohn]

Can just add a python script file, which adds a __doc__ string literal """ to each object, although docstring and actual code would then be separated into different files which is not ideal.

[demisjohn]

Some links on adding Python docstrings to Boost code. It sounds complicated as it's all in the Boost c-wrapper thingy, which I don't understand yet:

https://stackoverflow.com/questions/15625065/define-a-boostfunction-with-a-docstring-boostpython
https://stackoverflow.com/questions/18340500/boostpython-long-structured-docstrings
Boost documentation: https://www.boost.org/doc/libs/1_61_0/libs/python/doc/html/reference/function_invocation_and_creation/function_documentation.html

[demisjohn]

@jsenellart , do you have any insight into this issue? This is something I would love to work on, but the C/BOOST/Python wrapper functionality is beyond my pay grade. I'd love to find a way to type the Python docstring directly into the cpp file where the functions are defined, rather than in a separate python file.