update doc section for spin_xxx methods. (#2730)

Signed-off-by: Tomoya Fujita <[email protected]>
Co-authored-by: William Woodall <[email protected]>

Author: fujitatomoya

rclcpp/include/rclcpp/executor.hpp

@@ -287,6 +287,18 @@ class Executor
    * Adding subscriptions, timers, services, etc. with blocking or long running
    * callbacks may cause the function exceed the max_duration significantly.
    *
+   * Work that is ready to be done is collected only once, and when collecting that work
+   * entities which may have multiple pieces of work ready will only be executed at most
+   * one time.
+   * The reason for this is that it is not possible to tell if, for example, a ready
+   * subscription has only one message ready or multiple without checking again.
+   * Because, in order to find out if there are multiple messages, one message must
+   * be taken and executed before checking again if that subscription is still ready.
+   * However, this function only checks for ready entities to work on once,
+   * and so it will never execute a single entity more than once per call to this function.
+   * See spin_all() variants for a function that will repeatedly work on a single entity
+   * in a single call.
+   *
    * If there is no work to be done when this called, it will return immediately
    * because the collecting of available work is non-blocking.
    * Before each piece of ready work is executed this function checks if the