Review Documentation

[aronsho]

Review Documentation

[schmidni]

@aronsho @lmizrahi @martahan @RitzVanille @AliciaRoh

Things that are currently not consistently done in docstrings (and therefore inconsistent in documentation):

• Capitalize the descriptions of the arguments and finish with a dot.
• We are using type hints, and default values are also visible from the method signature, both are therefore not needed in the argument descriptions. “The description should include required type(s) if the code does not contain a corresponding type annotation.”
• It is possible to use mathematical equations also in docstrings, refer to this doc, I’ll add it there on my next pull request.
• Use tabs to align things, even if they are not represented in the generated documentation, it makes it easier to read inside the code.
• In the “Returns” part, you also need to give a name to the returned object, “somename: Description of the returned object” otherwise the formatting will be bad. If you don’t have a good idea, just call it “x”.

We are using this style guide. If you are unsure, or people are doing inconsistent things, refer to it. Following this style guide should also work with the parsing for the documentation.