Skip to content

Documenting functors composition

Composition is now largely adopted to create new functors and it is well-documented at the implementation level, however there is still missing a more wide and not-experts directed proper documentation. It would be ideal to have a dedicated section here, but there are also few additional side-comments.

As follows there are pointed out few ideas to improve/set up a proper documentation, feel free to comment and/or modify them:

  • In the section of ThOr functors reference, automatically generated from init by the docstrings, the composition of functors is not immediately comprehensive, in particular when the functor is composed in this way FUNCTOR = SOMETHING @ _FUNCTOR. One possible solution could be adding docstrings directly when defining the functor itself, i.e.
def FUNCTOR():
'''docstring with the definition of what the functor does''' 
   return SOMETHING @ _FUNCTOR

One typical example is when we have Optional functors, which require a ValueOr to handle the std::nullopt cases

  • Related to the previous point, to document the composition of functors it could be useful to specify in the docstrings the input and output of each functor, therefore users could have an idea about how to chain functors without looking directly at their implementation
  • While writing how composition works, particular attention should be given to specific functors that are not could not be easy to understand for newbies (for example TES, RELATIONS or VALUE_OR).
  • (A bit out-of-context) it could be useful to classify functors on the base of their functionality, for example "physics-based" ones vs "functional-based" ones and reorder a bit the init file (which is now in a messy situation) on the base of this distinction

Afaik there is already an open MR, so maybe it is possible to start from that point to update/renew the doc + add some Rec MRs to fix the docstrings in the init. It is a big intent which involves both RTA and DPA parts, so let me tag some people and feel free to add anyone who could be interested to participate to this project 😄

TODO:

  • While documenting, pay attention if the MR is properly tested and add related tests whenever it is necessary (see related issue here)

cc: @graven, @gligorov, @mvesteri, @poluekt, @erodrigu, @pkoppenb, @sstahl, @gunther, @amathad, @jzhuo, @fpolci

Edited by Tommaso Fulghesu