docs: ThOr functor documentation: ComposedBoundFunctor docstrings, and functors do not go into enough detail about functor inputs/outputs and intended use
Apologies as I have not worked a great deal on functors themselves recently, so I may not be completely correct about some of the underlying framework details, and most of this issue springs from my point of view as an "analysis" user rather than developer, thinking about "analysts" that are new to the software.
It's really nice that we have this comprehensive reference list of functors now, and this is a somewhat nit-picky issue. But, I think that it is becoming less clear (especially now since more of the "user-facing" / "user-friendly" functors are being defined as ComposedBoundFunctors
) in what context the "simpler" building-block functors should be used, particularly what count as 'legal' @
combinations of functors and what are the valid input and output types.
Additionally, from the docstrings it's less clear which functors are intended to be used directly (i.e. by users for selections, or tupling algorithms) vs. to build other functors / construct more complex quantities (could these be put into another category so analysis users don't need to think about them?)
For example, if one is to stumble across this in isolation:
They might pick F.ETA_COORDINATE
instead of F.ETA
. Can ETA_COORDINATE be used on its own, or is it intended to be used with some other type(s)? e.g. F.ETA_COORDINATE @ F.SLOPES
- could we add individual docstrings to
ComposedBoundFunctor
objects? what is the input type and output type of theComposedBoundFunctor
? can it be used out of the box in the context of a selection or tupling? - could we explain better in the docs what the
@
operator is doing and why we need it? (I was very confused when it was introduced) - indicate when a functor is designed to be used in a non-obvious way to the analysis end-user e.g. not on a composite or basic particle(s), returning number(s)
- To avoid the previous point, could we create different categories to try and distance the analysis end-user from these more "expert" building-block functors. Then, allow the "analysis" user to assume that for "non-expert" functors, an input will always be particle(s) and output will be e.g. number(s)