add note about problems with spin_until_future_complete

[alsora]

Description

The spin_until_future_complete can lead to unexpected behaviors.
It will only check if the future is complete when the timeout expires or after executing an executor's entity.

This will work as expected only if there's an event waking up the executor when the future becomes ready.
For example this will happen when doing a ROS client request and receiving a future.

auto future = client.async_send_request(request);
executor.spin_until_future_complete(future);

But it will not work correctly for any other generic future

auto future = my_non_ros_stuff();
executor.spin_until_future_complete(future);

In particular we may end up spinning for a lot more after the future is complete.

Is this user-facing behavior change?

No, just adding a comment

Did you use Generative AI?

No

Additional Information

This same problem is discussed as part of #2475

[alsora]

Test failures are unrelated.
merging this doc-only change