DOC: Update the pandas.Series.str.count() docstring (Delhi)

pandas/core/strings.py

@@ -202,15 +202,43 @@ def str_count(arr, pat, flags=0):
     """
     Count occurrences of pattern in each string of the Series/Index.
 
+    This function is used to count the number of times a particular regex
+    pattern is repeated in each of the string elements of the
+    :class:`~pandas.Series`.
+
     Parameters
     ----------
-    pat : string, valid regular expression
-    flags : int, default 0 (no flags)
-        re module flags, e.g. re.IGNORECASE
+    pat : str
+        Valid regular expression.
+    flags : int, default 0, meaning no flags
+        Flags for re module, e.g. re.IGNORECASE.
 
     Returns
     -------
     counts : Series/Index of integer values
+
+    Notes
+    -----
+    Some characters need to be escaped when passing in pat.
+    eg. '$' has a special meaning in regex and must be escaped when finding
+    specifically this char.
+
+    Examples
+    --------
+    Take a look at
+    `this link <https://docs.python.org/3/howto/regex.html#compilation-flags>`_
+    for the list of all possible flags that can be used.
+
+    >>> s = pd.Series(['A', 'B', 'Aaba', 'Baca', np.nan, 'CABA', 'cat'])
+    >>> s.str.count('a')
+    0    0.0
+    1    0.0
+    2    2.0
+    3    2.0
+    4    NaN
+    5    0.0
+    6    1.0
+    dtype: float64
     """
     regex = re.compile(pat, flags=flags)
     f = lambda x: len(regex.findall(x))