[Aaravanand00]

Description

Fixes #2632

Per the discussion in #2632, update_entities() and EntityCollection::update() in rclcpp/executors/executor_entities_collection.hpp only invoke the on_added and on_removed callbacks when the entity's weak_ptr can be locked into a valid shared_ptr. If an entity has already expired before update_entities() runs, it is still removed from (or inserted into) the collection, but the callback is suppressed to prevent nullptr dereferences in executor callback implementations.

Previously, the docstrings stated that the callback fires for every entry added or removed without mentioning the valid/non-expired entity requirement, causing confusion when custom executor implementations expected callbacks for expired entries.

As suggested by @alsora in #2632 (Option 1), this PR updates the Doxygen documentation for update_entities and EntityCollection::update to clearly state this behavior.

Is this user-facing behavior change?

No code changes; documentation clarification only.

Did you use Generative AI?

AI was used to assist in formatting and verifying docstrings against ROS 2 linter standards.

Additional Information

• Verified locally with ament_cpplint --linelength=100 --filters=+whitespace/line_length (0 problems found).
• Verified locally with ament_uncrustify (0 code style divergence).

[github-actions]

ABI Compliance Check

✅ Verdict: compatible

Library	Verdict	Summary
libcomponent_manager.so	✅ compatible	No ABI changes detected.
librclcpp.so	✅ compatible	No ABI changes detected.
librclcpp_action.so	✅ compatible	No ABI changes detected.
librclcpp_lifecycle.so	✅ compatible	No ABI changes detected.

✅ libcomponent_manager.so — full abidiff report

Compared:

• Base: lib-base/libcomponent_manager.so
• Head: lib-pr/libcomponent_manager.so @ f59193c

(empty report — no differences printed by abidiff)

✅ librclcpp.so — full abidiff report

Compared:

• Base: lib-base/librclcpp.so
• Head: lib-pr/librclcpp.so @ f59193c

Functions changes summary: 0 Removed, 0 Changed (93 filtered out), 0 Added (3 filtered out) functions
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable

✅ librclcpp_action.so — full abidiff report

Compared:

• Base: lib-base/librclcpp_action.so
• Head: lib-pr/librclcpp_action.so @ f59193c

(empty report — no differences printed by abidiff)

✅ librclcpp_lifecycle.so — full abidiff report

Compared:

• Base: lib-base/librclcpp_lifecycle.so
• Head: lib-pr/librclcpp_lifecycle.so @ f59193c

(empty report — no differences printed by abidiff)

_{Updated for commit f59193c · check run · suppressions: /home/runner/work/_temp/ros2-abi-suppressions.txt}