DOC: update the DataFrame.count docstring (#20221)

* DataFrame.count docstring reworked, examples added

* review corrections

* review fixes + better description

* review fixes, full stop and backticks

* review fix: changed summary, added quoting

Author: joders

pandas/core/frame.py

@@ -5851,22 +5851,78 @@ def corrwith(self, other, axis=0, drop=False):
 
     def count(self, axis=0, level=None, numeric_only=False):
         """
-        Return Series with number of non-NA/null observations over requested
-        axis. Works with non-floating point data as well (detects NaN and None)
+        Count non-NA cells for each column or row.
+
+        The values `None`, `NaN`, `NaT`, and optionally `numpy.inf` (depending
+        on `pandas.options.mode.use_inf_as_na`) are considered NA.
 
         Parameters
         ----------
         axis : {0 or 'index', 1 or 'columns'}, default 0
-            0 or 'index' for row-wise, 1 or 'columns' for column-wise
-        level : int or level name, default None
-            If the axis is a MultiIndex (hierarchical), count along a
-            particular level, collapsing into a DataFrame
+            If 0 or 'index' counts are generated for each column.
+            If 1 or 'columns' counts are generated for each **row**.
+        level : int or str, optional
+            If the axis is a `MultiIndex` (hierarchical), count along a
+            particular `level`, collapsing into a `DataFrame`.
+            A `str` specifies the level name.
         numeric_only : boolean, default False
-            Include only float, int, boolean data
+            Include only `float`, `int` or `boolean` data.
 
         Returns
         -------
-        count : Series (or DataFrame if level specified)
+        Series or DataFrame
+            For each column/row the number of non-NA/null entries.
+            If `level` is specified returns a `DataFrame`.
+
+        See Also
+        --------
+        Series.count: number of non-NA elements in a Series
+        DataFrame.shape: number of DataFrame rows and columns (including NA
+            elements)
+        DataFrame.isna: boolean same-sized DataFrame showing places of NA
+            elements
+
+        Examples
+        --------
+        Constructing DataFrame from a dictionary:
+
+        >>> df = pd.DataFrame({"Person":
+        ...                    ["John", "Myla", None, "John", "Myla"],
+        ...                    "Age": [24., np.nan, 21., 33, 26],
+        ...                    "Single": [False, True, True, True, False]})
+        >>> df
+           Person   Age  Single
+        0    John  24.0   False
+        1    Myla   NaN    True
+        2    None  21.0    True
+        3    John  33.0    True
+        4    Myla  26.0   False
+
+        Notice the uncounted NA values:
+
+        >>> df.count()
+        Person    4
+        Age       4
+        Single    5
+        dtype: int64
+
+        Counts for each **row**:
+
+        >>> df.count(axis='columns')
+        0    3
+        1    2
+        2    2
+        3    3
+        4    3
+        dtype: int64
+
+        Counts for one level of a `MultiIndex`:
+
+        >>> df.set_index(["Person", "Single"]).count(level="Person")
+                Age
+        Person
+        John      2
+        Myla      1
         """
         axis = self._get_axis_number(axis)
         if level is not None: