Docstring improvements.

Author: kevinzakka

mink/solve_ik.py

@@ -48,7 +48,7 @@ def build_ik(
     damping: float = 1e-12,
     limits: Optional[Sequence[Limit]] = None,
 ) -> qpsolvers.Problem:
-    r"""Build quadratic program from current configuration and tasks.
+    r"""Build the quadratic program given the current configuration and tasks.
 
     The quadratic program is defined as:
 

mink/tasks/com_task.py

@@ -49,6 +49,12 @@ def __init__(
         self.set_cost(cost)
 
     def set_cost(self, cost: npt.ArrayLike) -> None:
+        """Set the cost of the CoM task.
+
+        Args:
+            cost: A vector of shape (1,) (aka identical cost for all coordinates),
+                or (3,) (aka different costs for each coordinate).
+        """
         cost = np.atleast_1d(cost)
         if cost.ndim != 1 or cost.shape[0] not in (1, self.k):
             raise TaskDefinitionError(
@@ -64,7 +70,8 @@ def set_target(self, target_com: npt.ArrayLike) -> None:
         """Set the target CoM position in the world frame.
 
         Args:
-            target_com: Desired center-of-mass position in the world frame.
+            target_com: A vector of shape (3,) representing the desired
+                center-of-mass position in the world frame.
         """
         target_com = np.atleast_1d(target_com)
         if target_com.ndim != 1 or target_com.shape[0] != (self.k):

mink/tasks/damping_task.py

@@ -11,26 +11,26 @@
 class DampingTask(PostureTask):
     r"""L2-regularization on joint velocities (a.k.a. *velocity damping*).
 
-    This low-priority task adds a Tikhonov/Levenberg-Marquardt term to the
-    quadratic program, making the Hessian strictly positive-definite and
-    selecting the **minimum-norm joint velocity** in any redundant or
-    near-singular situation. Formally it contributes:
+    This task, typically used with a low priority in the task stack, adds a
+    Levenberg-Marquardt term to the quadratic program, favoring **minimum-norm
+    joint velocities** in redundant or near-singular situations. Formally, it
+    contributes the following term to the quadratic program:
 
     .. math::
         \frac{1}{2}\,\Delta \mathbf{q}^\top \Lambda\,\Delta \mathbf{q},
 
     where :math:`\Delta \mathbf{q}\in\mathbb{R}^{n_v}` is the vector of joint
     displacements and :math:`\Lambda = \mathrm{diag}(\lambda_1, \ldots, \lambda_{n_v})`
-    is a diagonal matrix of per-DoF weights provided by ``cost``. A larger
-    :math:`\lambda_i` reduces motion in DoF :math:`i`; with no other active
-    tasks the robot remains at rest.
-
-    This task does not favor a particular posture—only small instantaneous
-    motion. If you need a posture bias, use an explicit :class:`~.PostureTask`.
+    is a diagonal matrix of per-DoF damping weights specified via ``cost``. A larger
+    :math:`\lambda_i` reduces motion in DoF :math:`i`. With no other active
+    tasks, the robot remains at rest. Unlike the `damping` parameter in
+    :func:`~.solve_ik`, which is uniformly applied to all DoFs, this task does
+    not affect the floating-base coordinates.
 
     .. note::
 
-        Floating-base coordinates are not affected by this task.
+        This task does not favor a particular posture, only small instantaneous motion.
+        If you need a posture bias, use :class:`~.PostureTask` instead.
 
     Example:
 
@@ -53,7 +53,7 @@ def compute_error(self, configuration: Configuration) -> np.ndarray:
         r"""Compute the damping task error.
 
         The damping task does not chase a reference; its desired joint velocity
-        is identically **zero**, so the error vector is always
+        is identically **zero**, so the task error is always:
 
         .. math:: e = \mathbf 0 \in \mathbb R^{n_v}.
 

mink/tasks/frame_task.py

@@ -14,13 +14,13 @@
 
 
 class FrameTask(Task):
-    """Regulate the position and orientation of a frame expressed in the world frame.
+    """Regulate the position and orientation of a frame of interest on the robot.
 
     Attributes:
         frame_name: Name of the frame to regulate, typically the name of body, geom
             or site in the robot model.
         frame_type: The frame type: `body`, `geom` or `site`.
-        transform_frame_to_world: Target pose of the frame.
+        transform_frame_to_world: Target pose of the frame in the world frame.
 
     Example:
 

mink/tasks/kinetic_energy_regularization_task.py

@@ -12,23 +12,24 @@
 
 
 class KineticEnergyRegularizationTask(BaseTask):
-    r"""Kinetic-energy regularization task.
+    r"""Kinetic-energy regularization.
 
-    This low-priority task adds a configuration-dependent quadratic term to the
-    QP objective that penalizes the system's kinetic energy. Formally, it contributes:
+    This task, often used with a low priority in the task stack, penalizes the system's
+    kinetic energy. Formally, it contributes the following term to the quadratic
+    program:
 
     .. math::
         \frac{1}{2}\, \lambda\, \Delta \mathbf{q}^\top M(\mathbf{q})\,\Delta \mathbf{q},
 
     where :math:`\Delta \mathbf{q}\in\mathbb{R}^{n_v}` is the vector of joint
-    displacements, :math:`M(\mathbf{q})` is the joint-space inertia matrix
-    (dependent on the current configuration), and :math:`\lambda` is the scalar
-    strength of the regularization.
+    displacements, :math:`M(\mathbf{q})` is the joint-space inertia matrix, and
+    :math:`\lambda` is the scalar strength of the regularization.
 
     .. note::
 
-        This task penalizes DoFs in proportion to their joint-space inertia, so
-        higher-inertia (i.e., heavier) links will move less.
+        This task can be seen as an inertia-weighted version of the
+        :class:`~.DampingTask`. Degrees of freedom with higher inertia will move less
+        for the same cost.
 
     .. warning::
 

mink/tasks/posture_task.py

@@ -15,10 +15,10 @@
 
 
 class PostureTask(Task):
-    """Regulate the joint angles of the robot towards a desired posture.
+    """Regulate joint angles towards a target posture.
 
-    Using this task with a low cost value is useful as a regularizer when the problem
-    is under-constrained.
+    Often used with a low priority in the task stack, this task acts like a regularizer,
+    biasing the solution toward a specific joint configuration.
 
     Attributes:
         target_q: Target configuration :math:`q^*`, of shape :math:`(n_q,)`. Units are
@@ -83,7 +83,8 @@ def set_target(self, target_q: npt.ArrayLike) -> None:
         """Set the target posture.
 
         Args:
-            target_q: Desired joint configuration.
+            target_q: A vector of shape (nq,) representing the desired joint
+                configuration.
         """
         target_q = np.atleast_1d(target_q)
         if target_q.ndim != 1 or target_q.shape[0] != (self.nq):
@@ -94,7 +95,7 @@ def set_target(self, target_q: npt.ArrayLike) -> None:
         self.target_q = target_q.copy()
 
     def set_target_from_configuration(self, configuration: Configuration) -> None:
-        """Set the target posture from the current configuration.
+        """Set the target posture by extracting it from the current configuration.
 
         Args:
             configuration: Robot configuration :math:`q`.