Migration notes on init (#2412)

Author: fmauch

doc/migration.rst

@@ -4,3 +4,49 @@ Migration Guides: Jazzy to Kilted
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This list summarizes important changes between Jazzy (previous) and Kilted (current) releases, where changes to user code might be necessary.
+
+hardware_interface
+******************
+
+* The preferred signature for the ``on_init`` method in all
+  ``hardware_interface::*Interface`` classes has changed (`#
+  2323 <https://github.com/ros-controls/ros2_control/pull/2323>`_) from
+
+  .. code-block:: cpp
+
+     CallbackReturn on_init(const hardware_interface::HardwareInfo& info)
+
+  to
+
+  .. code-block:: cpp
+
+     CallbackReturn on_init(const HardwareComponentInterfaceParams& params)
+
+  The ``HardwareInfo`` object can be accessed from the ``HardwareComponentInterfaceParams`` object using
+  ``params.hardware_info``. Hardware implementations implementing the ``on_init`` method should
+  update their method signature accordingly as the deprecated signature will be removed in a
+  future release.
+
+  See :ref:`writing_new_hardware_component` for advanced usage of the
+  ``HardwareComponentInterfaceParams`` object.
+
+* The preferred signature for the ``init()`` method in all
+  ``hardware_interface::*Interface`` classes has changed (`#
+  2344 <https://github.com/ros-controls/ros2_control/pull/2344>`_) from
+
+
+  .. code-block:: cpp
+
+     CallbackReturn init(const HardwareInfo & hardware_info, rclcpp::Logger logger, rclcpp::Clock::SharedPtr clock)
+
+  to
+
+  .. code-block:: cpp
+
+     CallbackReturn init(const hardware_interface::HardwareComponentParams & params)
+
+
+* The ``initialize`` methods of all hardware components (such as ``Actuator``, ``Sensor``, etc.)
+  have been updated from passing a ``const HardwareInfo &`` to passing a ``const
+  HardwareComponentParams &`` (`# 2323 <https://github.com/ros-controls/ros2_control/pull/2323>`_).
+  The old signatures are deprecated and will be removed in a future release.

hardware_interface/doc/writing_new_hardware_component.rst

@@ -75,17 +75,17 @@ The following is a step-by-step guide to create source files, basic tests, and c
                   });
                }
 
-         **Method 2: Using the Executor from `HardwareComponentParams`**
+         **Method 2: Using the Executor from `HardwareComponentInterfaceParams`**
 
-         For more advanced use cases where you need direct control over node creation, the ``on_init`` method can be configured to receive a ``HardwareComponentParams`` struct. This struct contains a ``weak_ptr`` to the ``ControllerManager``'s executor.
+         For more advanced use cases where you need direct control over node creation, the ``on_init`` method can be configured to receive a ``HardwareComponentInterfaceParams`` struct. This struct contains a ``weak_ptr`` to the ``ControllerManager``'s executor.
 
-         #. **Update ``on_init`` Signature**: First, your hardware interface must override the ``on_init`` version that takes ``HardwareComponentParams``.
+         #. **Update ``on_init`` Signature**: First, your hardware interface must override the ``on_init`` version that takes ``HardwareComponentInterfaceParams``.
 
             .. code-block:: cpp
 
                // In your <robot_hardware_interface_name>.hpp
                hardware_interface::CallbackReturn on_init(
-               const hardware_interface::HardwareComponentParams & params) override;
+               const hardware_interface::HardwareComponentInterfaceParams & params) override;
 
          #. **Lock and Use the Executor**: Inside ``on_init``, you must safely "lock" the ``weak_ptr`` to get a usable ``shared_ptr``. You can then create your own node and add it to the executor.