It's worth mentioning, for the contributors, to know that we prefer to follow some suggestions given in numpy's conventions on parameters: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard (section 4. Parameters). In particular, we prefer to have the default values mentioned in the docstring.

Examples:

max_features : int or float, optional (default=1.0)

algorithm : {‘ball_tree’, ‘kd_tree’, ‘brute’, ‘auto’}, optional
    Algorithm used to compute the nearest neighbors:
        - ‘ball_tree’ will use BallTree (default)
        - ‘kd_tree’ will use KDTree
        - ‘brute’ will use a brute-force search.
        - ‘auto’ will attempt to decide the most appropriate algorithm based on the values passed to fit method.

The default values can be taken in most cases from the function definition or the __init__ of the classes. There are exceptions such as when the parameter is set as warn, in which case the actual default value needs to be found in the code, if not present in the documentation.

Priority is with the cases where the default value is not mentioned. I guess the ones which don't follow the format can be left alone for now. However, should we say, if the docstring of a class is touched for this PR, all parameters should follow the convention?

AFAIK, we fail to follow the recommendation from numpy strictly when recording the default value. I doubt whether it's worthwhile to correct these formatting issue. I'm fine as long as the default value is added to the docstring.

It's worth mentioning, for the contributors, to know that we prefer to follow numpy's conventions on parameters: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard (section 4. Parameters)

However, section 4 says "Optional keyword parameters have default values, which are displayed as part of the function signature. They can also be detailed in the description".

Hence as along as the default value is in the signature, numpydoc standards do not force to put the default value in the docstring.

Fair enough, but I guess we still prefer to have the default values mentioned in the docstring. I'll update the post accordingly.

Then we should also mention it in the coding guidelines of the doc contributing section

However, section 4 says "Optional keyword parameters have default values, which are displayed as part of the function signature. They can also be detailed in the description".

Thanks @albertcthomas . I guess I'll close this one and let's focus on other important issues. At the same time, I won't reject PRs which improves the doc or the contributing guide.