add disclaimer about jerk limits in docstring

include/control_toolbox/rate_limiter.hpp

@@ -47,6 +47,13 @@ class RateLimiter
    * If max_* values are NAN, the respective limit is deactivated
    * If min_* values are NAN (unspecified), defaults to -max
    * If min_first_derivative_pos/max_first_derivative_neg values are NAN, symmetric limits are used
+   *
+   * Disclaimer about the jerk limits:
+   *    The jerk limit is only applied when accelerating or reverse_accelerating (i.e., "sign(jerk * accel) > 0").
+   *    This condition prevents oscillating closed-loop behavior, see discussion details in
+   *    https://github.com/ros-controls/control_toolbox/issues/240.
+   *    if you use this feature, you should perform a test to check that the behavior is really as you expect.
+   *
    */
   RateLimiter(
     T min_value = std::numeric_limits<double>::quiet_NaN(),
@@ -92,6 +99,8 @@ class RateLimiter
    * \param [in]      dt Time step [s]
    * \return Limiting factor (1.0 if none)
    * \see http://en.wikipedia.org/wiki/jerk_%28physics%29#Motion_control
+   * \note
+   * The jerk limit is only applied when accelerating or reverse_accelerating (i.e., "sign(jerk * accel) > 0").
    */
   T limit_second_derivative(T & v, T v0, T v1, T dt);