Description
There are many instances in the codebase where our docstring/typing convention is not followed. We'd like to work on improving this with your help!
Our convention looks like:
def function_name(parameter_1: Union[str, List[str]], parameter_2: Optional[int] = None, parameter_3: float = 42.0) -> Civilization:
r"""
Function that creates a simulation.
Args:
parameter_1 (`str` or `List[str]`):
Description of game level.
parameter_2 (`int`, *optional*):
Kardashev scale of civilization.
parameter_3 (`float`, defaults to `42.0`):
Difficulty scale.
Returns:
[`~simulations.objects.Civilization`]
A civilization simulation with provided initialization parameters.
"""Some examples that don't follow the docstring convention are:
- this: missing explanations
- this: does not contain mixin-related documentation whereas as this does
- this: function explanation after "Args", but should be before
- this: same reason as above
- this: incorrect indentation
There are also many places where docstrings are completely missing or inadequately explained. If you feel something needs an improvement, you can open a PR with your suggestions too! Additionally, type hints are not appropriate/correctly used at many occurrences and mismatch the accompanying docstrings - these could use an improvement too!
Please limit your PRs to changes to a single file in each PR. Changes must be only related to docstrings/type hints. Feel free to ping either @yiyixuxu, @stevhliu or me for reviews.