@@ -358,13 +358,13 @@ def Rand(
 
         Return an SE2 instance with random rotation and translation.
 
-        - ``SE2.Rand()`` is a random SE(2) rotation.
+        - ``SE2.Rand()`` is a random SE(2) pose.
         - ``SE2.Rand(N)`` is an SE2 object containing a sequence of N random
           poses.
 
         Example, create random ten vehicles in the xy-plane::
 
-            >>> x = SE3.Rand(N=10, xrange=[-2,2], yrange=[-2,2])
+            >>> x = SE2.Rand(N=10, xrange=[-2,2], yrange=[-2,2])
             >>> len(x)
             10
 
 
@@ -105,7 +105,7 @@ def isprismatic(self):
         if len(self) == 1:
             return smb.iszerovec(self.w)
         else:
-            return [smb.iszerovec(x.w) for x in self.data]
+            return [smb.iszerovec(x.w) for x in self]
 
     @property
     def isrevolute(self):
@@ -131,7 +131,7 @@ def isrevolute(self):
         if len(self) == 1:
             return smb.iszerovec(self.v)
         else:
-            return [smb.iszerovec(x.v) for x in self.data]
+            return [smb.iszerovec(x.v) for x in self]
 
     @property
     def isunit(self):
@@ -296,13 +296,30 @@ class Twist3(BaseTwist):
     3D rigid body transformation which is the unique elements of the Lie
     algebra se(3) of the corresponding SE(3) matrix.
 
+    A twist can be used in two ways which share the same 6-vector, the same
+    :math:`[\vec{v}, \omega]` layout and the same algebra:
+
+    - as a *displacement*, where ``exp(S)`` is the pose reached by following the
+      screw motion and ``exp(S * theta)`` scales it.  ``S`` is often a unit
+      twist, see :meth:`unit`.  This is the usage in Robotics, Vision & Control
+      and in Modern Robotics.
+    - as a *velocity*, where ``S`` has units of m/s and rad/s and ``exp(S * dt)``
+      is the pose change over a time ``dt``.  This is the meaning of ``Twist``
+      in ROS.  The typed counterpart, which also has acceleration, force and
+      momentum, is :class:`~spatialmath.spatialvector.SpatialVelocity`.
+
+    Properties that describe the screw axis, such as :attr:`pitch`,
+    :attr:`pole` and :meth:`line`, are unchanged by scaling the twist so apply
+    to both.  Those that depend on its magnitude, such as :attr:`theta`, are
+    an angle in the first usage and a rate in the second.
+
     :References:
         - Robotics, Vision & Control for Python, Section 2.3.2.3, P. Corke, Springer 2023.
         - Modern Robotics, Lynch & Park, Cambridge 2017
 
     .. note:: Compared to Lynch & Park this module implements twist vectors
         with the translational components first, followed by rotational
-        components, ie. :math:`[\omega, \vec{v}]`.
+        components, ie. :math:`[\vec{v}, \omega]`.
 
     """
 
@@ -364,8 +381,8 @@ def isvalid(v, check=True):
         """
         Test if matrix is valid twist
 
-        :param x: array to test
-        :type x: ndarray
+        :param v: array to test
+        :type v: ndarray
         :return: Whether the value is a 6-vector or a valid 4x4 se(3) element
         :rtype: bool
 
@@ -538,7 +555,7 @@ def Rx(cls, theta, unit="rad"):
         :return: 3D twist vector
         :rtype: Twist3 instance
 
-        - ``Twist3.Rx(θ)`` is an SE(3) rotation of θ radians about the x-axis
+        - ``Twist3.Rx(θ)`` is an se(3) rotation of θ radians about the x-axis
         - ``Twist3.Rx(θ, "deg")`` as above but θ is in degrees
 
         If ``θ`` is an array then the result is a sequence of rotations defined
@@ -569,7 +586,7 @@ def Ry(cls, theta, unit="rad", t=None):
         :return: 3D twist vector
         :rtype: Twist3 instance
 
-        - ``Twist3.Ry(θ)`` is an SO(3) rotation of θ radians about the y-axis
+        - ``Twist3.Ry(θ)`` is an se(3) rotation of θ radians about the y-axis
         - ``Twist3.Ry(θ, "deg")`` as above but θ is in degrees
 
         If ``θ`` is an array then the result is a sequence of rotations defined
@@ -600,7 +617,7 @@ def Rz(cls, theta, unit="rad", t=None):
         :return: 3D twist vector
         :rtype: Twist3 instance
 
-        - ``Twist3.Rz(θ)`` is an SO(3) rotation of θ radians about the z-axis
+        - ``Twist3.Rz(θ)`` is an se(3) rotation of θ radians about the z-axis
         - ``Twist3.Rz(θ, "deg")`` as above but θ is in degrees
 
         If ``θ`` is an array then the result is a sequence of rotations defined
@@ -765,14 +782,14 @@ def Rand(
         :type zrange: 2-element sequence, optional
         :param N: number of random transforms
         :type N: int
-        :return: SE(3) matrix
-        :rtype: SE3 instance
+        :return: 3D twist
+        :rtype: Twist3 instance
 
-        Return an SE3 instance with random rotation and translation.
+        Return a Twist3 instance with random rotation and translation.
 
-        - ``SE3.Rand()`` is a random SE(3) translation.
-        - ``SE3.Rand(N=N)`` is an SE3 object containing a sequence of N random
-          poses.
+        - ``Twist3.Rand()`` is a random se(3) twist.
+        - ``Twist3.Rand(N=N)`` is a Twist3 object containing a sequence of N random
+          twists.
 
         Example:
 
@@ -781,7 +798,7 @@ def Rand(
             >>> from spatialmath import Twist3
             >>> Twist3.Rand(N=2)
 
-        :seealso: :func:`~spatialmath.quaternions.UnitQuaternion.Rand`
+        :seealso: :meth:`~spatialmath.pose3d.SE3.Rand`
         """
         from spatialmath.pose3d import SO3
 
@@ -792,7 +809,7 @@ def Rand(
             low=yrange[0], high=yrange[1], size=N
         )  # random values in the range
         Z = np.random.uniform(
-            low=yrange[0], high=zrange[1], size=N
+            low=zrange[0], high=zrange[1], size=N
         )  # random values in the range
         R = SO3.Rand(N=N)
 
@@ -1028,7 +1045,7 @@ def exp(self, theta=1, unit="rad"):
         """
         Exponentiate a 3D twist
 
-        :param theta: rotation magnitude, defaults to None
+        :param theta: rotation magnitude, defaults to 1
         :type theta: float, optional
         :param units: rotational units, defaults to 'rad'
         :type units: str, optional
@@ -1037,7 +1054,7 @@ def exp(self, theta=1, unit="rad"):
 
         - ``X.exp()`` is the homogeneous transformation equivalent to the twist,
           :math:`e^{[S]}`
-        - ``X.exp(θ) as above but with a rotation of ``θ`` about the twist axis,
+        - ``X.exp(θ)`` as above but with a rotation of ``θ`` about the twist axis,
           :math:`e^{\theta[S]}`
 
         If ``len(X)==1`` and ``len(θ)==N`` then the resulting SE3 object has
@@ -1173,7 +1190,7 @@ def __rmul__(
         - ``s * X`` performs elementwise multiplication of the elements of ``X`` by ``s``
         """
         if smb.isscalar(left):
-            return Twist3(right.S * left)
+            return Twist3(right.binop(left, lambda x, y: x * y))
         else:
             raise ValueError("Twist3 *, incorrect left operand")
 
@@ -1188,10 +1205,10 @@ def __str__(self):
 
         Example:
 
-        .. runblock: pycon
+        .. runblock:: pycon
 
             >>> from spatialmath import Twist3
-            >>> x = Twist3.R([1,2,3], [4,5,6])
+            >>> x = Twist3.UnitRevolute([1,2,3], [4,5,6])
             >>> print(x)
         """
         return "\n".join(
@@ -1212,13 +1229,11 @@ def __repr__(self):
 
         Example:
 
-        .. runblock: pycon
+        .. runblock:: pycon
 
             >>> from spatialmath import Twist3
-            >>> x = Twist3.R([1,2,3], [4,5,6])
+            >>> x = Twist3.UnitRevolute([1,2,3], [4,5,6])
             >>> x
-            >>> a.append(a)
-            >>> a
 
         """
         if len(self) == 0:
@@ -1265,12 +1280,25 @@ def _repr_pretty_(self, p, cycle):
 
 
 class Twist2(BaseTwist):
+    r"""
+    2D twist class
+
+    A Twist2 object holds the parameters of a twist, a representation of a
+    2D rigid body transformation which is the unique elements of the Lie
+    algebra se(2) of the corresponding SE(2) matrix.  It is a 3-vector
+    :math:`[\vec{v}, \omega]`.
+
+    As for :class:`Twist3` it can be used as a *displacement*, where ``exp(S)``
+    is the pose reached by following the motion, or as a *velocity*, where
+    ``exp(S * dt)`` is the pose change over a time ``dt``.  Properties that
+    describe the axis, such as :attr:`pole`, are unchanged by scaling the twist.
+    """
+
     def __init__(self, arg=None, w=None, check=True):
         r"""
             Construct a new 2D Twist object
 
-            :type a: 2-element array-like
-            :return: 2D prismatic twist
+            :return: 2D twist
             :rtype: Twist2 instance
 
             - ``Twist2(R)`` is a 2D Twist object representing the SO(2) rotation expressed as
@@ -1280,15 +1308,15 @@ def __init__(self, arg=None, w=None, check=True):
             - ``Twist2(X)`` if X is an SO2 instance then create a 2D Twist object representing the SO(2) rotation,
               and if X is an SE2 instance then create a 2D Twist object representing the SE(2) motion
             - ``Twist2(V)`` is a  2D Twist object specified directly by a 3-element array-like comprising the
-              moment vector (1 element) and direction vector (2 elements).
+              moment vector (2 elements) and direction vector (1 element).
 
         :References:
             - Robotics, Vision & Control for Python, Section 2.2.2.4, P. Corke, Springer 2023.
             - Modern Robotics, Lynch & Park, Cambridge 2017
 
         .. note:: Compared to Lynch & Park this module implements twist vectors
             with the translational components first, followed by rotational
-            components, ie. :math:`[\omega, \vec{v}]`.
+            components, ie. :math:`[\vec{v}, \omega]`.
         """
         from spatialmath.pose2d import SE2
 
@@ -1338,12 +1366,12 @@ def isvalid(v, check=True):
         """
         Test if matrix is valid twist
 
-        :param x: array to test
-        :type x: ndarray
+        :param v: array to test
+        :type v: ndarray
         :return: Whether the value is a 3-vector or a valid 3x3 se(2) element
         :rtype: bool
 
-        A twist can be represented by a 6-vector or a 4x4 skew symmetric matrix,
+        A twist can be represented by a 3-vector or a 3x3 augmented skew symmetric matrix,
         for example:
 
         .. runblock:: pycon
@@ -1379,7 +1407,7 @@ def UnitRevolute(cls, q):
 
         :param q: Point on the line of action
         :type q: array_like(2)
-        :return: 2D prismatic twist
+        :return: 2D revolute twist
         :rtype: Twist2 instance
 
         - ``Twist2.UnitRevolute(q)`` is a 2D Twist object representing rotation about the 2D point ``q``.
@@ -1523,7 +1551,7 @@ def SE2(self, theta=1, unit="rad"):
         Convert 2D twist to SE(2) matrix
 
         :return: an SE(2) representation
-        :rtype: SE3 instance
+        :rtype: SE2 instance
 
         ``S.SE2()`` is an SE2 object representing the homogeneous transformation
         equivalent to the Twist2. This is the exponentiation of the twist vector.
@@ -1536,12 +1564,12 @@ def SE2(self, theta=1, unit="rad"):
             >>> S = Twist2.UnitPrismatic([1,2])
             >>> S.SE2()
 
-        :seealso: :func:`Twist3.exp`
+        :seealso: :func:`Twist2.exp`
         """
         from spatialmath.pose2d import SE2
 
         if unit != "rad" and any(s.isprismatic for s in self):
-            print("Twist3.exp: using degree mode for a prismatic twist")
+            print("Twist2.SE2: using degree mode for a prismatic twist")
 
         theta = smb.getunit(theta, unit)
 
@@ -1584,7 +1612,7 @@ def exp(self, theta=1, unit="rad"):
         r"""
         Exponentiate a 2D twist
 
-        :param theta: rotation magnitude, defaults to None
+        :param theta: rotation magnitude, defaults to 1
         :type theta: float, optional
         :param unit: rotational units, defaults to 'rad'
         :type unit: str, optional
@@ -1593,7 +1621,7 @@ def exp(self, theta=1, unit="rad"):
 
         - ``X.exp()`` is the homogeneous transformation equivalent to the twist,
           :math:`e^{[S]}`
-        - ``X.exp(θ) as above but with a rotation of ``θ`` about the twist axis,
+        - ``X.exp(θ)`` as above but with a rotation of ``θ`` about the twist axis,
           :math:`e^{\theta[S]}`
 
         Example:
@@ -1728,7 +1756,7 @@ def Tx(cls, x):
         :return: 2D twist vector
         :rtype: Twist2 instance
 
-        `Twist2.Tx(x)` is an se(2) translation of ``x`` along the x-axis
+        ``Twist2.Tx(x)`` is an se(2) translation of ``x`` along the x-axis
 
         Example:
 
@@ -1754,7 +1782,7 @@ def Ty(cls, y):
         :return: 2D twist vector
         :rtype: Twist2 instance
 
-        `Twist2.Ty(y) is an se(2) translation of ``y`` along the y-axis
+        ``Twist2.Ty(y)`` is an se(2) translation of ``y`` along the y-axis
 
         Example:
 
@@ -1833,11 +1861,25 @@ def __mul__(
         else:
             raise ValueError("Twist2 *, incorrect right operand")
 
-    def __rmul(self, left):
+    def __rmul__(
+        right, left
+    ):  # lgtm[py/not-named-self] pylint: disable=no-self-argument
+        """
+        Overloaded ``*`` operator
+
+        :arg right: right multiplicand
+        :arg left: left multiplicand
+        :return: product
+        :raises: ValueError
+
+        Left-multiplication by a scalar
+
+        - ``s * X`` performs elementwise multiplication of the elements of ``X`` by ``s``
+        """
         if smb.isscalar(left):
-            return Twist2(self.S * left)
+            return Twist2(right.binop(left, lambda x, y: x * y))
         else:
-            raise ValueError("twist *, incorrect left operand")
+            raise ValueError("Twist2 *, incorrect left operand")
 
     def __str__(self):
         """
@@ -1850,8 +1892,9 @@ def __str__(self):
 
         Example:
 
-        .. runblock: pycon
+        .. runblock:: pycon
 
+            >>> from spatialmath import Twist2
             >>> x = Twist2([1,2,3])
             >>> print(x)
         """
@@ -1866,13 +1909,11 @@ def __repr__(self):
 
         Example:
 
-        .. runblock: pycon
+        .. runblock:: pycon
 
             >>> from spatialmath import Twist2
             >>> x = Twist2([1,2,3])
             >>> x
-            >>> a.append(a)
-            >>> a
 
         """