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

[fujitatomoya]

we need the indents here?

Suggested change

	* If this future is unrelated to an executor's entity, this method will not detect correctly
	* when it's completed.
	* If this future is unrelated to an executor's entity, this method will not detect correctly
	* when it's completed.

[christophebedard]

Minor fix + indentation to match the rest:

Suggested change

	* \note This method will check the future and the timeout only when the executor is woke up.
	* If this future is unrelated to an executor's entity, this method will not detect correctly
	* when it's completed.
	* \note This method will check the future and the timeout only when the executor is woken up.
	* If this future is unrelated to an executor's entity, this method will not detect correctly
	* when it's completed.

Should we also be more explicit about what could happen, e.g., "will not correctly detect when it's completed and therefore may wait forever and never time out."