Repository: pandas-dev/pandas
Pull request: DOC: Add note to docstring DataFrame.compare about identical labels
- [x] closes #35491
- [x] tests added / passed
- [x] passes `black pandas`
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`


Problem statement:
DOC: Add note to DataFrame.compare about only able to compare identically-labeled DataFrame objects
#### Location of the documentation
`pandas.core.frame::compare`

#### Documentation problem
Right now there is not a note/warning that you can only compare dataframes with the same shape and index labels.

#### Suggested fix for documentation
Add note: 

> Note: the method can only compare identically-labeled DataFrame objects, this means DataFrames with identical row and column labels.

Hints from issue discussion:
take

Commit message: Removed trailing whitespace

Patch to review:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index 4668f264000e7..4bf4b9d2122c6 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -5932,14 +5932,23 @@ def _construct_result(self, result) -> "DataFrame":
     The resulting index will be a MultiIndex with 'self' and 'other'
     stacked alternately at the inner level.
 
+Raises
+------
+ValueError
+    * When both DataFrames don't have identical labels or shape.
+
 See Also
 --------
 Series.compare : Compare with another Series and show differences.
+DataFrame.equals : Test whether two objects contain the same elements.
 
 Notes
 -----
 Matching NaNs will not appear as a difference.
 
+Can only compare identically-labeled DataFrame objects,
+this means DataFrames with the same shape and identical row, column labels.
+
 Examples
 --------
 >>> df = pd.DataFrame(


Code review comments:
diff_hunk: @@ -5932,14 +5932,23 @@ def _construct_result(self, result) -> "DataFrame":
     The resulting index will be a MultiIndex with 'self' and 'other'
     stacked alternately at the inner level.
 
+Raises
+------
+ValueError
+    * When both DataFrames don't have identical labels or shape.
path: pandas/core/frame.py
text: @user1:
First, the formatting looks a bit different to other docstrings, e.g. in pandas/core/algorithms.py we find

```
    Raises
    ------
    IndexError
        When `indices` is out of bounds for the array.
    ValueError
        When the indexer contains negative values other than ``-1``
        and `allow_fill` is True.
```

, is the bullet point `* ` like this used elsewhere in the codebase?

Second, I think the usage of "both" here isn't usual, how about:

```
ValueError
    When the two DataFrames don't have identical labels or shape.
```

@author:
Yes, first I had two raises, so had bullet points, forgot to remove later. Adjusted this.