Update throttle logging docs with units and data type hints (re: rclc…

…pp/issues/1929) (#3143)

* Note milliseconds on API Concepts page

* Add units and types to About Logging page

Co-authored-by: dan <dan@polarworks.no>
Co-authored-by: Chris Lalancette <clalancette@openrobotics.org>

source/Concepts/About-Logging.rst

@@ -53,15 +53,15 @@ These are the APIs that end users of the ROS 2 logging infrastructure should use
     * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_EXPRESSION`` - output the given printf-style message only if the given expression is true
     * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_FUNCTION`` - output the given printf-style message only if the given function returns true
     * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_SKIPFIRST`` - output the given printf-style message all but the first time this line is hit
-    * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_THROTTLE`` - output the given printf-style message no more than the given rate
-    * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_SKIPFIRST_THROTTLE`` - output the given printf-style message no more than the given rate, but skip the first
+    * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_THROTTLE`` - output the given printf-style message no more than the given rate in integer milliseconds
+    * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_SKIPFIRST_THROTTLE`` - output the given printf-style message no more than the given rate in integer milliseconds, but skip the first
     * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM`` - output the given C++ stream-style message every time this line is hit
     * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM_ONCE`` - output the given C++ stream-style message only the first time this line is hit
     * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM_EXPRESSION`` - output the given C++ stream-style message only if the given expression is true
     * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM_FUNCTION`` - output the given C++ stream-style message only if the given function returns true
     * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM_SKIPFIRST`` - output the given C++ stream-style message all but the first time this line is hit
-    * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM_THROTTLE`` - output the given C++ stream-style message no more than the given rate
-    * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM_SKIPFIRST_THROTTLE`` - output the given C++ stream-style message no more than the given rate, but skip the first
+    * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM_THROTTLE`` - output the given C++ stream-style message no more than the given rate in integer milliseconds
+    * ``RCLCPP_{DEBUG,INFO,WARN,ERROR,FATAL}_STREAM_SKIPFIRST_THROTTLE`` - output the given C++ stream-style message no more than the given rate in integer milliseconds, but skip the first
 
     Each of the above APIs takes an ``rclcpp::Logger`` object as the first argument.
     This can be pulled from the node API by calling ``node->get_logger()`` (recommended), or by constructing a stand-alone ``rclcpp::Logger`` object.
@@ -73,7 +73,7 @@ These are the APIs that end users of the ROS 2 logging infrastructure should use
 
     * ``logger.{debug,info,warning,error,fatal}`` - output the given Python string to the logging infrastructure.  The calls accept the following keyword args to control behavior:
 
-      * ``throttle_duration_sec`` - if not None, the duration of the throttle interval
+      * ``throttle_duration_sec`` - if not None, the duration of the throttle interval in floating-point seconds
       * ``skip_first`` - if True, output the message all but the first time this line is hit
       * ``once`` - if True, only output the message the first time this line is hit
 

source/Tutorials/Demos/Logging-and-logger-configuration.rst

@@ -91,7 +91,9 @@ The following code will output a log message from a ROS 2 node at ``WARN`` sever
 Logging throttled
 ^^^^^^^^^^^^^^^^^
 
-The following code will output a log message from a ROS 2 node at ``ERROR`` severity, but no more than once per second:
+The following code will output a log message from a ROS 2 node at ``ERROR`` severity, but no more than once per second.
+
+The interval parameter specifying milliseconds between messages should have an integer data type so it can be converted to a ``rcutils_duration_value_t`` (an ``int64_t``):
 
 .. tabs::
 
@@ -105,6 +107,9 @@ The following code will output a log message from a ROS 2 node at ``ERROR`` seve
             // C++ stream style
             RCLCPP_ERROR_STREAM_THROTTLE(node->get_logger(), *node->get_lock(), 1000, "My log message " << 4);
 
+            // For now, use the nanoseconds() method to use an existing rclcpp::Duration value, see https://github.com/ros2/rclcpp/issues/1929
+            RCLCPP_ERROR_STREAM_THROTTLE(node->get_logger(), *node->get_clock(), msg_interval.nanoseconds()/1000000, "My log message " << 4);
+
     .. group-tab:: Python
 
         .. code-block:: python