clarify RigidBodyAcceleration's usage

src/samples/RigidBodyAcceleration.cpp

@@ -2,7 +2,12 @@
 
 namespace base { namespace samples {
 
-void RigidBodyAcceleration::invalidateOrientation()
+RigidBodyAcceleration::RigidBodyAcceleration()
+{
+    invalidate();
+}
+
+void RigidBodyAcceleration::invalidate()
 {
     cov_acceleration = Eigen::Matrix3d::Identity();
     cov_acceleration *= INFINITY;

src/samples/RigidBodyAcceleration.hpp

@@ -5,24 +5,41 @@
 #include <base/Time.hpp>
 
 namespace base { namespace samples {
-    struct RigidBodyAcceleration 
+    /**
+     * Representation of accelerations of a body in a given (unspecified) fixed
+     * frame of reference
+     *
+     * While the frame of reference is unspecified, it will usually be the
+     * inertial frame. We encourage Rock code to use the body-fixed frame
+     * as the frame of expression.
+     *
+     * Indeed, Sensors (e.g. gyros, accelerometers) and models (e.g.
+     * hydrodynamic models) give access to velocities and accelerations w.r.t.
+     * the inertial frame, but expressed in the body frame. However, expressing
+     * the velocities/accelerations in the world frame from these
+     * sensing/estimation methods would require to have an estimate
+     * of the system's pose in the world, which is a harder thing to get.
+     */
+    struct RigidBodyAcceleration
     {
+        RigidBodyAcceleration();
+
         base::Time time;
 
-        /** Linear acceleration in m/s2, world fixed frame of reference (East-North-Up) */
+        /** Linear acceleration in m/s2 */
         base::Vector3d acceleration;
-	/** Covariance matrix of the linear acceleration
-	 */
+        /** Covariance matrix of the linear acceleration
+         */
         base::Matrix3d cov_acceleration;
 
-        /** Angular acceleration in rad/s2, world fixed frame of reference (East-North-Up) */
+        /** Angular acceleration in rad/s2 */
         base::Vector3d angular_acceleration;
-	/** Covariance matrix of the angular acceleration
-	 */
+        /** Covariance matrix of the angular acceleration
+         */
         base::Matrix3d cov_angular_acceleration;
 
-	void invalidateOrientation();
-	
+        void invalidate();
+
     };
 }}