Add remark on getFrameClassicalAcceleration (#2169)

* Add remark on getFrameClassicalAcceleration

* Update the changelog

* Update include/pinocchio/algorithm/frames.hpp

Thanks @traversaro

* Correct the remark thanks to @traversaro

* Add remark to getFrameAcceleration as well

CHANGELOG.md

@@ -18,7 +18,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Clean up empty documentation pages and sections ([#2167](https://github.com/stack-of-tasks/pinocchio/pull/2167))
 
 ### Added
-- Add `examples/floating-base-velocity-viewer.py` to visualize floating base velocity [#2143](https://github.com/stack-of-tasks/pinocchio/pull/2143)
+- Add `examples/floating-base-velocity-viewer.py` to visualize floating base velocity ([#2143](https://github.com/stack-of-tasks/pinocchio/pull/2143))
+- Add remark to the documentation of `getFrame(Classical)Acceleration` functions ([#2169](https://github.com/stack-of-tasks/pinocchio/pull/2169))
 
 ## [2.7.0] - 2024-01-23
 

include/pinocchio/algorithm/frames.hpp

@@ -102,7 +102,7 @@ namespace pinocchio
 
   /**
    * @brief      Returns the spatial acceleration of the Frame expressed in the desired reference frame.
-   *             You must first call pinocchio::forwardKinematics to update placement, velocity and acceleration values in data structure.
+   *             You must first call pinocchio::forwardKinematics to update placement, velocity and acceleration values in the data structure.
    *
    * @param[in]  model       The kinematic model
    * @param[in]  data        Data associated to model
@@ -111,7 +111,13 @@ namespace pinocchio
    *
    * @return The spatial acceleration of the Frame expressed in the desired reference frame.
    *
-   * @warning    Second order forwardKinematics should have been called first
+   * @warning    Second order @ref forwardKinematics should have been called first
+   *
+   * @remark     In the context of a frame placement constraint \f$J(q) a + \dot{J}(q, v) v = 0\f$,
+   *             one way to compute the second term \f$\dot{J}(q, v) v\f$ is to call second-order @ref forwardKinematics with a zero acceleration,
+   *             then read the remaining \f$\dot{J}(q, v) v\f$ by calling this function.
+   *             This is significantly more efficient than applying the matrix \f$\dot{J}(q, v)\f$ (from @ref getFrameJacobianTimeVariation)
+   *             to the velocity vector \f$v\f$.
    */
   template<typename Scalar, int Options, template<typename,int> class JointCollectionTpl>
   inline MotionTpl<Scalar, Options>
@@ -132,7 +138,14 @@ namespace pinocchio
    *
    * @return The classical acceleration of the Frame expressed in the desired reference frame.
    *
-   * @warning    Second order forwardKinematics should have been called first
+   * @warning    Second order @ref forwardKinematics should have been called first
+   *
+   * @remark     In the context of a frame placement constraint \f$J(q) a + \dot{J}(q, v) v = 0\f$,
+   *             one way to compute the second term \f$\dot{J}(q, v) v\f$ is to call second-order @ref forwardKinematics with a zero acceleration,
+   *             then read the remaining \f$\dot{J}(q, v) v\f$ by calling this function.
+   *             This is significantly more efficient than applying the matrix \f$\dot{J}(q, v)\f$ (from @ref getFrameJacobianTimeVariation)
+   *             to the velocity vector \f$v\f$.
+   *
    */
   template<typename Scalar, int Options, template<typename,int> class JointCollectionTpl>
   inline MotionTpl<Scalar, Options>