Skip to content

Add docstrings for functors

Tommaso Fulghesu requested to merge tfulghes-documentation-docstrings into master

The idea to add a significant docstring for each functor helps to address the first point of #435.

To have a coherent description of the functor in the automatically generated ThOr functors reference section, few changes have been applied in the following MR:

  • Composed functors which have no arguments generally have a not very comprehensive description, for example CHI2 functor is:
ComposedBoundFunctor:
(
  VALUE_OR()
@
  _CHI2()
)

without specifying the descriptions for each functor used in the composition. Furthermore every functor named with _ prefix is ignored from the documentation by this line, so it could be nice have a docstring associated to CHI2 functor itself and a useful link to the source code showing explicitly the composition.

  • Parameters have been added whenever missing under the args section for docstrings
  • For functors with missing or incomplete docstrings, a docstring has been added/updated

TODO:

  • Add docstrings for functors that are composed but accepting no arguments
  • Make __doc__ attribute writable to add custom docstrings
  • Check that the Moore script that auto-generate the references displays the correct __doc__ attribute and add link to source code
  • Check if link to external webpage is correctly reproduced
  • Tests for making functors references documentation

This MR is independent from other projects. It is related to Moore!1996 (merged), that could be considered the continuation of this work. The desired final result might have a significant description for every functor's reference, with a proper link that point to the script where the functor is implemented (c++ header for elementary functors and python reference for the composed ones).

Edited by Tommaso Fulghesu

Merge request reports