update comments and docstrings

Author: jorisvandenbossche

pandas/core/frame.py

@@ -6103,15 +6103,15 @@ def _dispatch_frame_op(self, right, func, axis: Optional[int] = None):
             #  fails in cases with empty columns reached via
             #  _frame_arith_method_with_reindex
 
-            # TODO operate_blockwise expects a manager of the same type
+            # TODO operate_manager expects a manager of the same type
             bm = self._mgr.operate_manager(right._mgr, func)  # type: ignore[arg-type]
 
         elif isinstance(right, Series):
             if axis == 1:
                 # axis=1 means we want to operate row-by-row
                 assert right.index.equals(self.columns)
             else:
-                assert right.index.equals(self.index)  # Handle other cases later
+                assert right.index.equals(self.index)
 
             right = right._values
             bm = self._mgr.operate_array(right, func, axis)

pandas/core/internals/managers.py

@@ -20,7 +20,7 @@
 import numpy as np
 
 from pandas._libs import internals as libinternals, lib
-from pandas._typing import ArrayLike, Dtype, DtypeObj, Shape
+from pandas._typing import ArrayLike, Dtype, DtypeObj, Scalar, Shape
 from pandas.errors import PerformanceWarning
 from pandas.util._validators import validate_bool_kwarg
 
@@ -367,24 +367,51 @@ def reduce(
             new_mgr = type(self).from_blocks(res_blocks, [self.items, index])
         return new_mgr, indexer
 
-    def operate_scalar(self, other, op) -> BlockManager:
+    def operate_scalar(self, other: Scalar, op) -> BlockManager:
         """
-        TODO fill in
+        Element-wise (arithmetic/comparison/logical) operation with other scalar.
+
+        Parameters
+        ----------
+        other : scalar
+        op : operator function (eg ``operator.add``)
+
+        Returns
+        -------
+        BlockManager
         """
         # Get the appropriate array-op to apply to each column/block's values.
         array_op = ops.get_array_op(op)
         return self.apply(array_op, right=other)
 
     def operate_array(self, other: ArrayLike, op, axis: int) -> BlockManager:
         """
-        TODO fill in
+        Element-wise (arithmetic/comparison/logical) operation with other array.
+
+        The array is already checked to be of the correct length.
+
+        Parameters
+        ----------
+        other : np.ndarray or ExtensionArray
+        op : operator function (eg ``operator.add``)
+        axis : int
+            Whether to match the array on the index and broadcast along the
+            columns (axis=0) or match the array on the columns and broadcast
+            along the rows (axis=1).
+
+        Returns
+        -------
+        BlockManager
         """
         array_op = ops.get_array_op(op)
         if axis == 1:
+            # match on the columns -> operate on each column array with single
+            # element from other array
             arrays = [
                 array_op(self.iget_values(i), _right) for i, _right in enumerate(other)
             ]
         else:
+            # match on the rows -> operate for each column array with full other array
             arrays = [
                 array_op(self.iget_values(i), other) for i in range(len(self.items))
             ]
@@ -393,15 +420,20 @@ def operate_array(self, other: ArrayLike, op, axis: int) -> BlockManager:
 
     def operate_manager(self, other: BlockManager, op) -> BlockManager:
         """
-        TODO fill in
-        """
-        array_op = ops.get_array_op(op)
-        return self.operate_blockwise(other, array_op)
+        Element-wise (arithmetic/comparison/logical) operation with other BlockManager.
 
-    def operate_blockwise(self, other: BlockManager, array_op) -> BlockManager:
-        """
-        Apply array_op blockwise with another (aligned) BlockManager.
+        The other BlockManager is already aligned with `self`.
+
+        Parameters
+        ----------
+        other : BlockManager
+        op : operator function (eg ``operator.add``)
+
+        Returns
+        -------
+        BlockManager
         """
+        array_op = ops.get_array_op(op)
         return operate_blockwise(self, other, array_op)
 
     def apply(