Decide on how we handle docstrings in subclasses
Created by: jpoeppel
PR #5 made it apparent that we do not currently have decided on how we want to handle docstrings in subclasses (especially from abstract classes). More or less copying does not appear to be reasonable as it only makes it easier to have inconsistent docstrings when we need to change something. Just referencing the superclass in the docstring of the subclass has the problem of not being introspection friendly to IDEs. Furthermore, in the case where additional parameters are possible, it is not clear where to put their description. We should decide on one approach to use throughout the codebase.
Options that I see currently:
- Superclass holds precise docstrings, entailing information about all parameters and what the function is supposed to do. The subclasses would then reference that docstring while making clear if they implement an extension or override the original function, as well as any special behaviour that differs from what was specified in the superclass
- Superclasses (especially abstract ones) will only contain minimal docstrings, stating the general idea of the functions and maybe the types of the parameters. Only the subclasses provide the concrete descriptions (will most likely not work well for non-abstract superclasses as they should have proper docstrings on their own).
- Both super- and subclasses have full docstrings explaining everything relevant to their current implementation. This requires a lot of duplication of docstrings though.
I guess I would currently favour option 1. Maybe while still providing information about the parameters in the subclasses to aid introspection in IDEs.