Repository: pandas-dev/pandas
Pull request: DOC: Improve examples of df.append to better show the ignore_index param
Change index to [0, 2] to stress that ignore_index=True resets the index of both dataframes

- [x] closes #41407 
- [x] tests passed
- [x] Ensure all linting tests pass, see [here](https://pandas.pydata.org/pandas-docs/dev/development/contributing.html#code-standards) for how to run them
- [x] whatsnew entry

Test Output: 

```
################################################################################
################################## Validation ##################################
################################################################################

1 Errors found:
	Return value has no description
```



Problem statement:
DOC: Unclear first example in pandas.DataFrame.append
#### Location of the documentation

pandas.DataFrame.append 

#### Documentation problem

I think the example chosen to show the difference between ignore_index=False and ignore_index = True (the very first on the page) could make this difference more clear.

#### Suggested fix for documentation

Choosing a custom index for the first df (the one whose append function is called) could help to especially point out the fact that ignore_index=True actually overwrites the whole index and does not keep the index of the first dataframe, as it could be interpreted from this example (given somebody dared to not read the doc above 😉 )

Hints from issue discussion:
yes I agree. Thanks for the report. Do feel free to contribute this idea via a PR!
On it :)

Commit message: DOC: add Return description #41407

Patch to review:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index 2941b6ac01904..e5adf0da741eb 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -8793,6 +8793,7 @@ def append(
         Returns
         -------
         DataFrame
+            A new DataFrame consisting of the rows of caller and the rows of `other`.
 
         See Also
         --------
@@ -8811,18 +8812,18 @@ def append(
 
         Examples
         --------
-        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=list('AB'))
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=list('AB'), index=[0, 2])
         >>> df
            A  B
         0  1  2
-        1  3  4
-        >>> df2 = pd.DataFrame([[5, 6], [7, 8]], columns=list('AB'))
+        2  3  4
+        >>> df2 = pd.DataFrame([[5, 6], [7, 8]], columns=list('AB'), index=[0, 4])
         >>> df.append(df2)
            A  B
         0  1  2
-        1  3  4
+        2  3  4
         0  5  6
-        1  7  8
+        4  7  8
 
         With `ignore_index` set to True:
 


Code review comments:
diff_hunk: @@ -8811,18 +8812,18 @@ def append(
 
         Examples
         --------
-        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=list('AB'))
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=list('AB'), index=[0, 2])
path: pandas/core/frame.py
text: @user2:
The comment from @user1 finding the original clearer, I agree with, why do you not change the index here to ["x", "y"] and for df2. Then you achieve; highlighting the non-unique element created; avoid any confusion with the same 0,1 and indexes which are only conincidentally the same in the original example; and demonstrate the index has a dtype change rom string to base RangeIndex.

@author:
Yes, that sounds good!