DOC: Enhance the docstrings to provide more detailed explanations for the functions and their parameters in Common.py

[himanshurd]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://github.com/pandas-dev/pandas/blob/main/pandas/tests/arithmetic/common.py

Documentation problem

def assert_cannot_add(left, right, msg="cannot add"):
"""
Helper to assert that left and right cannot be added.

Parameters
----------
left : object
right : object
msg : str, default "cannot add"
"""
with pytest.raises(TypeError, match=msg):
    left + right
with pytest.raises(TypeError, match=msg):
    right + left

def assert_invalid_addsub_type(left, right, msg=None):
"""
Helper to assert that left and right can be neither added nor subtracted.

Parameters
----------
left : object
right : object
msg : str or None, default None
"""
with pytest.raises(TypeError, match=msg):
    left + right
with pytest.raises(TypeError, match=msg):
    right + left
with pytest.raises(TypeError, match=msg):
    left - right
with pytest.raises(TypeError, match=msg):
    right - left

Suggested fix for documentation

Enhance the docstrings to provide more detailed explanations for the functions and their parameters.

def assert_cannot_add(left, right, msg="cannot add"):
"""
Helper function to assert that two objects cannot be added.

Parameters
----------
left : object
    The first operand.
right : object
    The second operand.
msg : str, default "cannot add"
    The error message expected in the TypeError.
"""
with pytest.raises(TypeError, match=msg):
    left + right
with pytest.raises(TypeError, match=msg):
    right + left

Ensure function names are consistent and descriptive.

def assert_invalid_add_subtraction(left, right, msg=None):
"""
Helper function to assert that two objects can neither be added nor subtracted.

Parameters
----------
left : object
    The first operand.
right : object
    The second operand.
msg : str or None, default None
    The error message expected in the TypeError.
"""
with pytest.raises(TypeError, match=msg):
    left + right
with pytest.raises(TypeError, match=msg):
    right + left
with pytest.raises(TypeError, match=msg):
    left - right
with pytest.raises(TypeError, match=msg):
    right - left

[santhoshbethi]

take

[Aloqeely]

Thanks for the suggestion!
The current name for the second function is still descriptive in my opinion and so I am against that change, changing function names should not be done lightly.

But the parameter descriptions seem helpful, PRs are welcome to add them!

[santhoshbethi]

Thanks @Aloqeely . I have created the PR with the suggested changes. Please check it once here #58830