Updated set_index parameter append along with an example

Author: SaraInCode

pandas/core/frame.py

@@ -5868,10 +5868,6 @@ def set_index(
         columns or arrays (of the correct length). The index can replace the
         existing index or expand on it.
 
-        .. warning::
-            Setting a new index will remove the current index column,
-            unless you first call `reset_index`.
-
         Parameters
         ----------
         keys : label or array-like or list of labels/arrays
@@ -5884,6 +5880,8 @@ def set_index(
             Delete columns to be used as the new index.
         append : bool, default False
             Whether to append columns to existing index.
+            Setting to True will add the new columns to existing index.
+            When set to False, the current index will be dropped from the DataFrame.
         inplace : bool, default False
             Whether to modify the DataFrame rather than creating a new one.
         verify_integrity : bool, default False
@@ -5957,6 +5955,25 @@ def set_index(
         2 4       4  2014    40
         3 9       7  2013    84
         4 16     10  2014    31
+
+        Append a column to the existing index:
+
+        >>> df.set_index("month", inplace=True)
+        >>> df.set_index("year", append=True)
+                      sale
+        month  year
+        1      2012    55
+        4      2014    40
+        7      2013    84
+        10     2014    31
+
+        >>> df.set_index("year", append=False)
+               sale
+        year
+        2012    55
+        2014    40
+        2013    84
+        2014    31
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         self._check_inplace_and_allows_duplicate_labels(inplace)