Hi there,There are few things regarding the docstrings, that are still open to discussion, in many cases because the numpy convention (or numpy doc examples) is different for the unwritten convention used in most pandas docstrings.Probably you've seen the discussion in GitHub, but I list them here, with the proposed decision (mainly keep the pandas way). If anyone disagrees in any point, please let us know, so we'll change the documentation for the sprint, and do it in the desired way.1) Starting the docstring just after the opening triple quotes, or in the next line. In pandas it's more common to do it in the next line, so we'll keep it this way.2) For parameters, showing the default value after the type, or after the description. Numpy does not find it necessary to specify them, and it specified the recommended place is after the description. The proposal (mainly by Joris) is to always have them and after the type, as it's easier to see it.3) For parameters expecting a string, in the numpy convention examples `str` is used, the proposal is to use `string` instead.4) For complex types like dicts, I think there is some consensus that is easier to understand the types if using brackets (e.g. "dict of {str: int}" over "dict of str: int"). And same for tuples (e.g. "tuple of (int, str, int)" over "tuple of int, str, int"). For list and sets, the type is simpler (e.g. "list of int" or "set of str"). I propose to use the brackets for list and tuple, and not for list and set, and use `str` over `string` if part of a complex type.5) For cases where a parameter is optional, so, have a None value by default, meaning the value is not required (as I understand if it was the case of `fillna(value=None)` value wouldn't be optional, as it means is the value used to replace `NaN`). In this case, the proposal is to use as the type, something like "int or float, optional" over "int, float or None (default None)".6) When the parameter expects something in the form of a Python list, a numpy array, a pandas Series... document it as "array-like" over other options list "iterable" or "numpy.array, Series or list".Thanks!
_______________________________________________
Pandas-dev mailing list
Pandas-dev@python.org
https://mail.python.org/mailman/listinfo/pandas-dev