Updating docstring guide documentation with last changes

Author: Marc Garcia

pandas/guide/source/pandas_docstring.rst

@@ -91,16 +91,17 @@ General rules
 ~~~~~~~~~~~~~
 
 Docstrings must be defined with three double-quotes. No blank lines should be
-left before or after the docstring. The text starts immediately after the
-opening quotes (not in the next line). The closing quotes have their own line
+left before or after the docstring. The text starts in the next line after the
+opening quotes. The closing quotes have their own line
 (meaning that they are not at the end of the last sentence).
 
 **Good:**
 
 .. code-block:: python
 
     def func():
-        """Some function.
+        """
+        Some function.
 
         With a good docstring.
         """
@@ -114,19 +115,18 @@ opening quotes (not in the next line). The closing quotes have their own line
 
     def func():
 
-        """
-        Some function.
+        """Some function.
 
         With several mistakes in the docstring.
-        
+
         It has a blank like after the signature `def func():`.
-        
-        The text 'Some function' should go in the same line as the
-        opening quotes of the docstring, not in the next line.
-        
+
+        The text 'Some function' should go in the next line then the
+        opening quotes of the docstring, not in the same line.
+
         There is a blank line between the docstring and the first line
         of code `foo = 1`.
-        
+
         The closing quotes should be in the next line, not in this one."""
 
         foo = 1
@@ -150,7 +150,8 @@ details.
 .. code-block:: python
 
     def astype(dtype):
-        """Cast Series type.
+        """
+        Cast Series type.
 
         This section will provide further details.
         """
@@ -161,28 +162,32 @@ details.
 .. code-block:: python
 
     def astype(dtype):
-        """Casts Series type.
+        """
+        Casts Series type.
 
         Verb in third-person of the present simple, should be infinitive.
         """
         pass
 
     def astype(dtype):
-        """Method to cast Series type.
+        """
+        Method to cast Series type.
 
         Does not start with verb.
         """
         pass
 
     def astype(dtype):
-        """Cast Series type
+        """
+        Cast Series type
 
         Missing dot at the end.
         """
         pass
 
     def astype(dtype):
-        """Cast Series type from its current type to the new type defined in
+        """
+        Cast Series type from its current type to the new type defined in
         the parameter dtype.
 
         Summary is too verbose and doesn't fit in a single line.
@@ -201,10 +206,14 @@ go in other sections.
 A blank line is left between the short summary and the extended summary. And
 every paragraph in the extended summary is finished by a dot.
 
+The extended summary should provide details on why the function is useful and
+their use cases, if it is not too generic.
+
 .. code-block:: python
 
     def unstack():
-        """Pivot a row index to columns.
+        """
+        Pivot a row index to columns.
 
         When using a multi-index, a level can be pivoted so each value in
         the index becomes a column. This is especially useful when a subindex
@@ -239,19 +248,28 @@ can have multiple lines. The description must start with a capital letter, and
 finish with a dot.
 
 Keyword arguments with a default value, the default will be listed in brackets
-at the end of the description (before the dot). The exact form of the
-description in this case would be "Description of the arg (default is X).". In
-some cases it may be useful to explain what the default argument means, which
-can be added after a comma "Description of the arg (default is -1, which means
-all cpus).".
+at the end of the type. The exact form of the type in this case would be for
+example "int (default is 0)". In some cases it may be useful to explain what
+the default argument means, which can be added after a comma "int (default is
+-1, which means all cpus)".
+
+In cases where the default value is `None`, meaning that the value will not be
+used, instead of "str (default is None)" it is preferred to use "str, optional".
+When `None` is a value being used, we will keep the form "str (default None).
+For example consider `.fillna(value=None)`, in which `None` is the value being
+used to replace missing values. This is different from
+`.to_csv(compression=None)`, where `None` is not a value being used, but means
+that compression is optional, and will not be used, unless a compression type
+is provided. In this case we will use `str, optional`.
 
 **Good:**
 
 .. code-block:: python
 
     class Series:
         def plot(self, kind, color='blue', **kwargs):
-            """Generate a plot.
+            """
+            Generate a plot.
 
             Render the data in the Series as a matplotlib plot of the
             specified kind.
@@ -260,8 +278,8 @@ all cpus).".
             ----------
             kind : str
                 Kind of matplotlib plot.
-            color : str
-                Color name or rgb code (default is 'blue').
+            color : str (default 'blue')
+                Color name or rgb code.
             **kwargs
                 These parameters will be passed to the matplotlib plotting
                 function.
@@ -274,7 +292,8 @@ all cpus).".
 
     class Series:
         def plot(self, kind, **kwargs):
-            """Generate a plot.
+            """
+            Generate a plot.
 
             Render the data in the Series as a matplotlib plot of the
             specified kind.
@@ -302,26 +321,33 @@ Parameter types
 ^^^^^^^^^^^^^^^
 
 When specifying the parameter types, Python built-in data types can be used
-directly:
+directly (the Python type is preferred to the more verbose string, integer,
+boolean, etc):
 
 - int
 - float
 - str
 - bool
 
-For complex types, define the subtypes:
+For complex types, define the subtypes. For `dict` and `tuple`, as more than
+one type is present, we use the brackets to help read the type (curly brackets
+for `dict` and normal brackets for `tuple`):
 
-- list of [int]
+- list of int
 - dict of {str : int}
 - tuple of (str, int, int)
-- set of {str}
+- tuple of (str,)
+- set of str
 
-In case there are just a set of values allowed, list them in curly brackets
-and separated by commas (followed by a space). If one of them is the default
-value of a keyword argument, it should be listed first.:
+In case where there are just a set of values allowed, list them in curly
+brackets and separated by commas (followed by a space). If the values are
+ordinal and they have an order, list them in this order. Otherwuse, list
+the default value first, if there is one:
 
 - {0, 10, 25}
 - {'simple', 'advanced'}
+- {'low', 'medium', 'high'}
+- {'cat', 'dog', 'bird'}
 
 If the type is defined in a Python module, the module must be specified:
 
@@ -357,7 +383,7 @@ last two types, that need to be separated by the word 'or':
 - float, decimal.Decimal or None
 - str or list of str
 
-If None is one of the accepted values, it always needs to be the last in
+If `None` is one of the accepted values, it always needs to be the last in
 the list.
 
 .. _docstring.returns:
@@ -384,7 +410,8 @@ For example, with a single value:
 .. code-block:: python
 
     def sample():
-        """Generate and return a random number.
+        """
+        Generate and return a random number.
 
         The value is sampled from a continuous uniform distribution between
         0 and 1.
@@ -401,7 +428,8 @@ With more than one value:
 .. code-block:: python
 
     def random_letters():
-        """Generate and return a sequence of random letters.
+        """
+        Generate and return a sequence of random letters.
 
         The length of the returned string is also random, and is also
         returned.
@@ -423,7 +451,8 @@ If the method yields its value:
 .. code-block:: python
 
     def sample_values():
-        """Generate an infinite sequence of random numbers.
+        """
+        Generate an infinite sequence of random numbers.
 
         The values are sampled from a continuous uniform distribution between
         0 and 1.
@@ -507,7 +536,9 @@ For example:
 
             See Also
             --------
-            tail : Return the last 5 elements of the Series.
+            Series.tail : Return the last 5 elements of the Series.
+            Series.iloc : Return a slice of the elements in the Series,
+                which can also be used to return the first or last n.
             """
             return self.iloc[:5]
 
@@ -637,15 +668,17 @@ one structure is needed, name them with something meaningful, for example
 `df_main` and `df_to_join`.
 
 Data used in the example should be as compact as possible. The number of rows
-is recommended to be 4, unless the example requires a larger number. As for
-example in the head method, where it requires to be higher than 5, to show
-the example with the default values.
-
-Avoid using data without interpretation, like a matrix of random numbers
-with columns A, B, C, D... And instead use a meaningful example, which makes
-it easier to understand the concept. Unless required by the example, use
-names of animals, to keep examples consistent. And numerical properties of
-them.
+is recommended to be around 4, but make it a number that makes sense for the
+specific example. For example in the `head` method, it requires to be higher
+than 5, to show the example with the default values. If doing the `mean`,
+we could use something like `[1, 2, 3]`, so it is easy to see that the
+value returned is the mean.
+
+For more complex examples (groupping for example), avoid using data without
+interpretation, like a matrix of random numbers with columns A, B, C, D...
+And instead use a meaningful example, which makes it easier to understand the
+concept. Unless required by the example, use names of animals, to keep examples
+consistent. And numerical properties of them.
 
 When calling the method, keywords arguments `head(n=3)` are preferred to
 positional arguments `head(3)`.
@@ -654,23 +687,58 @@ positional arguments `head(3)`.
 
 .. code-block:: python
 
-    def method():
-        """A sample DataFrame method.
+    class Series:
+        def mean(self):
+            """
+            Compute the mean of the input.
 
-        Examples
-        --------
-        >>> df = pd.DataFrame([389., 24., 80.5, numpy.nan]
-        ...                   columns=('max_speed'),
-        ...                   index=['falcon', 'parrot', 'lion', 'monkey'])
-        """
-        pass
+            Examples
+            --------
+            >>> s = pd.Series([1, 2, 3])
+            >>> s.mean()
+            2
+            """
+            pass
+
+
+        def fillna(self, value):
+            """
+            Replace missing values by `value`.
+
+            Examples
+            --------
+            >>> s = pd.Series([1, np.nan, 3])
+            >>> s.fillna(9)
+            [1, 9, 3]
+            """
+            pass
+
+        def groupby_mean(df):
+            """
+            Group by index and return mean.
+
+            Examples
+            --------
+            >>> s = pd.Series([380., 370., 24., 26],
+            ...               name='max_speed',
+            ...               index=['falcon', 'falcon', 'parrot', 'parrot'])
+            >>> s.groupby_mean()
+            falcon  375.
+            parrot   25.
+            """
+            pass
 
 **Bad:**
 
 .. code-block:: python
 
     def method():
-        """A sample DataFrame method.
+        """
+        A sample DataFrame method.
+
+        Do not import numpy and pandas.
+
+        Try to use meaningful data, when it adds value.
 
         Examples
         --------