From d0bc26b6e869c285d71a6322e4c117ca1f40b6a8 Mon Sep 17 00:00:00 2001 From: deepanshu Date: Wed, 13 Jul 2022 15:04:05 -0400 Subject: [PATCH] update node API's documentation based on pre and post callbacks Signed-off-by: deepanshu --- rclcpp/include/rclcpp/node.hpp | 90 ++++++++++++++++++++++++++++++---- 1 file changed, 81 insertions(+), 9 deletions(-) diff --git a/rclcpp/include/rclcpp/node.hpp b/rclcpp/include/rclcpp/node.hpp index 6e52c737ee..0417cfb3d8 100644 --- a/rclcpp/include/rclcpp/node.hpp +++ b/rclcpp/include/rclcpp/node.hpp @@ -336,11 +336,21 @@ class Node : public std::enable_shared_from_this * * If `ignore_override` is `true`, the parameter override will be ignored. * - * This method, if successful, will result in any callback registered with - * add_on_set_parameters_callback to be called. + * This method will result in any callback registered with + * `add_on_set_parameters_callback` and `add_post_set_parameters_callback` + * to be called for the parameter being set. + * + * If a callback was registered previously with `add_on_set_parameters_callback`, + * it will be called prior to setting the parameter for the node. * If that callback prevents the initial value for the parameter from being * set then rclcpp::exceptions::InvalidParameterValueException is thrown. * + * If a callback was registered previously with `add_post_set_parameters_callback`, + * it will be called after setting the parameter successfully for the node. + * + * This method will `not` result in any callbacks registered with + * `add_pre_set_parameters_callback` to be called. + * * The returned reference will remain valid until the parameter is * undeclared. * @@ -457,11 +467,22 @@ class Node : public std::enable_shared_from_this * If `ignore_overrides` is `true`, all the overrides of the parameters declared * by the function call will be ignored. * + * This method will result in any callback registered with + * `add_on_set_parameters_callback` and `add_post_set_parameters_callback` + * to be called once for each parameter. + * * This method, if successful, will result in any callback registered with - * add_on_set_parameters_callback to be called, once for each parameter. + * `add_on_set_parameters_callback` to be called, once for each parameter. * If that callback prevents the initial value for any parameter from being * set then rclcpp::exceptions::InvalidParameterValueException is thrown. * + * If a callback was registered previously with `add_post_set_parameters_callback`, + * it will be called after setting the parameters successfully for the node, + * once for each parameter. + * + * This method will `not` result in any callbacks registered with + * `add_pre_set_parameters_callback` to be called. + * * \param[in] namespace_ The namespace in which to declare the parameters. * \param[in] parameters The parameters to set in the given namespace. * \param[in] ignore_overrides When `true`, the parameters overrides are ignored. @@ -499,8 +520,9 @@ class Node : public std::enable_shared_from_this /// Undeclare a previously declared parameter. /** - * This method will not cause a callback registered with - * add_on_set_parameters_callback to be called. + * This method will not cause a callback registered with any of the + * `add_pre_set_parameters_callback`, `add_on_set_parameters_callback` and + * `add_post_set_parameters_callback` to be called. * * \param[in] name The name of the parameter to be undeclared. * \throws rclcpp::exceptions::ParameterNotDeclaredException if the parameter @@ -534,11 +556,24 @@ class Node : public std::enable_shared_from_this * Parameter overrides are ignored by set_parameter. * * This method will result in any callback registered with - * add_on_set_parameters_callback to be called. + * `add_pre_set_parameters_callback`, add_on_set_parameters_callback` and + * `add_post_set_parameters_callback` to be called once for the parameter + * being set. + * + * This method will result in any callback registered with + * `add_on_set_parameters_callback` to be called. * If the callback prevents the parameter from being set, then it will be * reflected in the SetParametersResult that is returned, but no exception * will be thrown. * + * If a callback was registered previously with `add_pre_set_parameters_callback`, + * it will be called once prior to the validation of the parameter for the node. + * If this callback makes modified parameter list empty, then it will be reflected + * in the returned result; no exceptions will be raised in this case. + * + * If a callback was registered previously with `add_post_set_parameters_callback`, + * it will be called once after setting the parameter successfully for the node. + * * If the value type of the parameter is rclcpp::PARAMETER_NOT_SET, and the * existing parameter type is something else, then the parameter will be * implicitly undeclared. @@ -575,11 +610,25 @@ class Node : public std::enable_shared_from_this * corresponding SetParametersResult in the vector returned by this function. * * This method will result in any callback registered with - * add_on_set_parameters_callback to be called, once for each parameter. + * `add_pre_set_parameters_callback`, `add_on_set_parameters_callback` and + * `add_post_set_parameters_callback` to be called once for each parameter. + + * If a callback was registered previously with `add_pre_set_parameters_callback`, + * it will be called prior to the validation of parameters for the node, + * once for each parameter. + * If this callback makes modified parameter list empty, then it will be reflected + * in the returned result; no exceptions will be raised in this case. + * + * This method will result in any callback registered with + * `add_on_set_parameters_callback` to be called, once for each parameter. * If the callback prevents the parameter from being set, then, as mentioned * before, it will be reflected in the corresponding SetParametersResult * that is returned, but no exception will be thrown. * + * If a callback was registered previously with `add_post_set_parameters_callback`, + * it will be called after setting the parameters successfully for the node, + * once for each parameter. + * * Like set_parameter() this method will implicitly undeclare parameters * with the type rclcpp::PARAMETER_NOT_SET. * @@ -606,11 +655,25 @@ class Node : public std::enable_shared_from_this * If the exception is thrown then none of the parameters will have been set. * * This method will result in any callback registered with - * add_on_set_parameters_callback to be called, just one time. + * `add_pre_set_parameters_callback`, `add_on_set_parameters_callback` and + * `add_post_set_parameters_callback` to be called only 'once' for all parameters. + * + * If a callback was registered previously with `add_pre_set_parameters_callback`, + * it will be called prior to the validation of node parameters, just one time + * for all parameters. + * If this callback makes modified parameter list empty, then it will be reflected + * in the returned result; no exceptions will be raised in this case. + * + * This method will result in any callback registered with + * 'add_on_set_parameters_callback' to be called, just one time. * If the callback prevents the parameters from being set, then it will be * reflected in the SetParametersResult which is returned, but no exception * will be thrown. * + * If a callback was registered previously with `add_post_set_parameters_callback`, + * it will be called after setting the node parameters successfully, just one time + * for all parameters. + * * If you pass multiple rclcpp::Parameter instances with the same name, then * only the last one in the vector (forward iteration) will be set. * @@ -884,7 +947,7 @@ class Node : public std::enable_shared_from_this * The modified list of parameters is then forwarded to the "on set parameter" * callback for validation. * - * The callback is called whenever any of the `set_parameter*` methods are called ' + * The callback is called whenever any of the `set_parameter*` methods are called * or when a set parameter service request is received. * * The callback takes a reference to the vector of parameters to be set. @@ -918,6 +981,8 @@ class Node : public std::enable_shared_from_this * The callback is not called when parameters are declared with `declare_parameter` * or `declare_parameters`. * + * The callback is not called when parameters are undeclared with `undeclare_parameter`. + * * An empty modified parameter list from the callback will result in "set_parameter*" * returning an unsuccessful result. * @@ -971,6 +1036,8 @@ class Node : public std::enable_shared_from_this * this callback, so when checking a new value against the existing one, you * must account for the case where the parameter is not yet set. * + * The callback is not called when parameters are undeclared with `undeclare_parameter`. + * * Some constraints like read_only are enforced before the callback is called. * * The callback may introspect other already set parameters (by calling any @@ -1040,6 +1107,11 @@ class Node : public std::enable_shared_from_this * * This callback should not modify parameters. * + * The callback is called when parameters are declared with `declare_parameter` + * or `declare_parameters`. See `declare_parameter` or `declare_parameters` above. + * + * The callback is not called when parameters are undeclared with `undeclare_parameter`. + * * If you want to make changes to parameters based on changes to another, use * `add_pre_set_parameters_callback`. *