DOC: Missing documentation for Series.__invert__() (~ operator)

[SebastianJL]

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

No current documentation.

Documentation problem

Today I was searching for documentation on what the ~ operator does in pandas. I was astounded to not find a page for Series.__invert__() or a documentation page about all operators. The only thing I could find was a sentence at the start of this https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#boolean-indexing and a few mentions in some release notes (e.g. https://pandas.pydata.org/docs/dev/whatsnew/v2.0.0.html) which seems a bit obscure to me.

Suggested fix for documentation

• Add documentation for Series.__invert__() and possibly for other types. This seems important to me because in regular python the tilde operator means bitwise invert (https://docs.python.org/3/library/operator.html#operator.__invert__) and in pandas it is elementwise invert. So that should be properly documented. It is better than existing documentation because it is easier to find when one is specifically looking for this information.
• An overview page over all operators would be nice but is not as urgent.

[rhshadrach]

Thanks for the report. I think we can more broadly consider this as an issue of documenting dunder methods in general. Some dunders are already documented, and while these methods mostly do the obvious thing there are cases that don't. I'm positive on documenting dunders across the board, with certain case-by-case exceptions (e.g. Series.__nonzero__, a relic from Python 2). For comparison, NumPy documents their dunders in the API docs. These often do not have much information, but some do.

If there is no opposition to documenting dunders, I can provide a list of methods here.

cc @pandas-dev/pandas-core