From d95ff3ece9c03b1f7e0aab97fb27dc7446acde51 Mon Sep 17 00:00:00 2001
From: abonte <6319051+abonte@users.noreply.github.com>
Date: Mon, 16 Jan 2023 19:28:20 +0100
Subject: [PATCH] DOC: improve Index docstrings (#50720)

* DOC: improve Index docstrings

* fix example

* update Series.hanans docstring
---
 pandas/core/base.py         |  4 +++
 pandas/core/indexes/base.py | 64 +++++++++++++++++++++++++++++++++----
 2 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/pandas/core/base.py b/pandas/core/base.py
index 826583fd26f5d..3f32f3cff8607 100644
--- a/pandas/core/base.py
+++ b/pandas/core/base.py
@@ -784,6 +784,10 @@ def hasnans(self) -> bool:
         Return True if there are any NaNs.
 
         Enables various performance speedups.
+
+        Returns
+        -------
+        bool
         """
         # error: Item "bool" of "Union[bool, ndarray[Any, dtype[bool_]], NDFrame]"
         # has no attribute "any"
diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
index f5757bc0e200e..bc8087db7b49b 100644
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -2041,13 +2041,21 @@ def is_monotonic_increasing(self) -> bool:
         """
         Return a boolean if the values are equal or increasing.
 
+        Returns
+        -------
+        bool
+
+        See Also
+        --------
+        Index.is_monotonic_decreasing : Check if the values are equal or decreasing.
+
         Examples
         --------
-        >>> Index([1, 2, 3]).is_monotonic_increasing
+        >>> pd.Index([1, 2, 3]).is_monotonic_increasing
         True
-        >>> Index([1, 2, 2]).is_monotonic_increasing
+        >>> pd.Index([1, 2, 2]).is_monotonic_increasing
         True
-        >>> Index([1, 3, 2]).is_monotonic_increasing
+        >>> pd.Index([1, 3, 2]).is_monotonic_increasing
         False
         """
         return self._engine.is_monotonic_increasing
@@ -2057,13 +2065,21 @@ def is_monotonic_decreasing(self) -> bool:
         """
         Return a boolean if the values are equal or decreasing.
 
+        Returns
+        -------
+        bool
+
+        See Also
+        --------
+        Index.is_monotonic_increasing : Check if the values are equal or increasing.
+
         Examples
         --------
-        >>> Index([3, 2, 1]).is_monotonic_decreasing
+        >>> pd.Index([3, 2, 1]).is_monotonic_decreasing
         True
-        >>> Index([3, 2, 2]).is_monotonic_decreasing
+        >>> pd.Index([3, 2, 2]).is_monotonic_decreasing
         True
-        >>> Index([3, 1, 2]).is_monotonic_decreasing
+        >>> pd.Index([3, 1, 2]).is_monotonic_decreasing
         False
         """
         return self._engine.is_monotonic_decreasing
@@ -2108,6 +2124,34 @@ def _is_strictly_monotonic_decreasing(self) -> bool:
     def is_unique(self) -> bool:
         """
         Return if the index has unique values.
+
+        Returns
+        -------
+        bool
+
+        See Also
+        --------
+        Index.has_duplicates : Inverse method that checks if it has duplicate values.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 5, 7, 7])
+        >>> idx.is_unique
+        False
+
+        >>> idx = pd.Index([1, 5, 7])
+        >>> idx.is_unique
+        True
+
+        >>> idx = pd.Index(["Watermelon", "Orange", "Apple",
+        ...                 "Watermelon"]).astype("category")
+        >>> idx.is_unique
+        False
+
+        >>> idx = pd.Index(["Orange", "Apple",
+        ...                 "Watermelon"]).astype("category")
+        >>> idx.is_unique
+        True
         """
         return self._engine.is_unique
 
@@ -2122,6 +2166,10 @@ def has_duplicates(self) -> bool:
         bool
             Whether or not the Index has duplicate values.
 
+        See Also
+        --------
+        Index.is_unique : Inverse method that checks if it has unique values.
+
         Examples
         --------
         >>> idx = pd.Index([1, 5, 7, 7])
@@ -2547,6 +2595,10 @@ def hasnans(self) -> bool:
         Return True if there are any NaNs.
 
         Enables various performance speedups.
+
+        Returns
+        -------
+        bool
         """
         if self._can_hold_na:
             return bool(self._isnan.any())