DOC: Add docs for Series.__invert__ (~); add cross-link from Boolean indexing

doc/source/reference/series.rst

@@ -107,6 +107,15 @@ Binary operator functions
    Series.product
    Series.dot
 
+Unary operator functions
+------------------------
+.. autosummary::
+   :toctree: api/
+
+   Series.__invert__
+
+
+
 Function application, GroupBy & window
 --------------------------------------
 .. autosummary::

doc/source/user_guide/indexing.rst

@@ -811,6 +811,10 @@ evaluate an expression such as ``df['A'] > 2 & df['B'] < 3`` as
 ``df['A'] > (2 & df['B']) < 3``, while the desired evaluation order is
 ``(df['A'] > 2) & (df['B'] < 3)``.
 
+For toggling boolean masks with the ``~`` operator, see
+:meth:`pandas.Series.__invert__`.
+
+
 Using a boolean vector to index a Series works exactly as in a NumPy ndarray:
 
 .. ipython:: python

pandas/core/ops/docstrings.py

@@ -781,3 +781,41 @@ def make_flex_doc(op_name: str, typ: str) -> str:
    B   True    False
    C   True    False
 """
+
+# --- add at bottom of pandas/core/ops/docstrings.py ---
+
+_doc_series_invert = """
+Bitwise NOT (``~``).
+
+For boolean dtype, behaves as logical NOT. Missing values (``NA``) propagate.
+For integer dtypes, performs bitwise inversion (two's complement) elementwise.
+
+Returns
+-------
+Series
+    Elementwise result with the same index and name.
+
+Notes
+-----
+On ``boolean[pyarrow]`` dtype, ``NA`` values also propagate under ``~``.
+
+See Also
+--------
+Series.__and__, Series.__or__, Series.__xor__
+
+Examples
+--------
+>>> s = pd.Series([True, False, pd.NA], dtype="boolean")
+>>> ~s
+0    False
+1     True
+2     <NA>
+dtype: boolean
+
+>>> s = pd.Series([1, 2, -3], dtype="Int32")
+>>> ~s
+0   -2
+1   -3
+2    2
+dtype: Int32
+"""

pandas/core/series.py

@@ -7338,3 +7338,7 @@ def cumsum(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Self:
     @doc(make_doc("cumprod", 1))
     def cumprod(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Self:
         return NDFrame.cumprod(self, axis, skipna, *args, **kwargs)
+
+# at bottom of pandas/core/series.py (after class Series ...)
+from pandas.core.ops.docstrings import _doc_series_invert
+Series.__invert__.__doc__ = _doc_series_invert