update node API's documentation based on pre and post callbacks

Signed-off-by: deepanshu <deepanshubansal01@gmail.com>

rclcpp/include/rclcpp/node.hpp

@@ -336,11 +336,21 @@ class Node : public std::enable_shared_from_this<Node>
    *
    * 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<Node>
    * 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<Node>
 
   /// 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<Node>
    * 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<Node>
    * 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<Node>
    * 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<Node>
    * 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<Node>
    * 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<Node>
    * 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<Node>
    *
    * 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`.
    *