doc: docstring

Signed-off-by: Zulfaqar Azmi <zulfaqar.azmi@tier4.jp>

Author: zulfaqar-azmi-t4

planning/autoware_trajectory_concatenator/include/autoware/trajectory_concatenator/detail/trajectory_concatenator.hpp

@@ -31,26 +31,37 @@ namespace autoware::trajectory_concatenator
 using autoware_internal_planning_msgs::msg::CandidateTrajectories;
 
 /**
- * @brief Stateful aggregator of trajectories from multiple generators.
- * Uses a most-recent-per-generator buffer with time-based stale pruning.
- * * * Pure C++ Library: This class is completely independent of rclcpp.
- * * Thread-safety: Not thread-safe. Must be protected by a mutex by the caller.
- * * ARCHITECTURAL NOTE ON LATENCY:
- * Because this stage is designed to be flushed via a fixed-rate timer (e.g., 30ms),
- * it introduces an average ~15ms (max 30ms) latency floor to the pipeline. Consequently,
- * all downstream outputs (including debug markers) are quantized to this timer's rate.
+ * @brief Aggregates candidate trajectories from multiple generators into a single set.
  */
 class TrajectoryConcatenator
 {
 public:
+  /**
+   * @brief Constructs the concatenator with the given parameters.
+   * @param params Initial concatenator parameters.
+   */
   explicit TrajectoryConcatenator(concatenator::Params params) : params_(std::move(params)) {}
 
+  /**
+   * @brief Replaces the current parameters.
+   * @param params New parameter values.
+   */
   void update_parameters(const concatenator::Params & params) { params_ = params; }
 
+  /**
+   * @brief Stores the latest trajectories from the message's generator.
+   * @param msg Candidate trajectories message from a single generator.
+   */
   void add_candidate(const CandidateTrajectories & msg);
 
+  /**
+   * @brief Returns the merged set of all non-stale generator trajectories.
+   * @param current_time Current ROS time used to filter out stale entries.
+   */
   [[nodiscard]] CandidateTrajectories get_concatenated(
     const builtin_interfaces::msg::Time & current_time);
+
+  /** @brief Returns and resets the elapsed processing time in milliseconds. */
   double take_processing_time();
 
 private:

planning/autoware_trajectory_concatenator/include/autoware/trajectory_concatenator/trajectory_concatenator_interface.hpp

@@ -28,9 +28,17 @@
 
 namespace autoware::trajectory_concatenator
 {
+/**
+ * @brief ROS2 adapter for TrajectoryConcatenator: handles parameter updates and thread safety.
+ */
 class TrajectoryConcatenatorInterface
 {
 public:
+  /**
+   * @brief Constructs the interface and initialises the concatenator with declared parameters.
+   * @param node ROS2 node used for parameter declaration and logging.
+   * @param node_parameters_interface Parameter interface for declaring and reading parameters.
+   */
   TrajectoryConcatenatorInterface(
     rclcpp::Node & node,
     rclcpp::node_interfaces::NodeParametersInterface::SharedPtr node_parameters_interface)
@@ -42,6 +50,7 @@ class TrajectoryConcatenatorInterface
   {
   }
 
+  /** @brief Reloads parameters from the parameter server if they have changed. */
   void update_parameters()
   {
     if (concatenator_params_listener_.is_old(concatenator_params_)) {
@@ -51,13 +60,18 @@ class TrajectoryConcatenatorInterface
     }
   }
 
+  /**
+   * @brief Adds a set of candidate trajectories to the buffer.
+   * @param candidate_trajectories Candidate trajectories from a single generator.
+   */
   void add_candidate(
     const autoware_internal_planning_msgs::msg::CandidateTrajectories & candidate_trajectories)
   {
     std::lock_guard<std::mutex> lock(concatenator_mutex_);
     concatenator_ptr_->add_candidate(candidate_trajectories);
   }
 
+  /** @brief Returns the merged set of all non-stale generator trajectories. */
   [[nodiscard]] autoware_internal_planning_msgs::msg::CandidateTrajectories get_concatenated()
   {
     update_parameters();
@@ -67,6 +81,8 @@ class TrajectoryConcatenatorInterface
     return concatenator_ptr_->get_concatenated(time_now);
   };
 
+  /** @brief Returns the interface name and elapsed processing time in milliseconds, then resets it.
+   */
   [[nodiscard]] std::pair<std::string, double> take_processing_time()
   {
     std::lock_guard<std::mutex> lock(concatenator_mutex_);

planning/autoware_trajectory_validator/include/autoware/trajectory_validator/detail/trajectory_validator.hpp

@@ -28,21 +28,37 @@ namespace autoware::trajectory_validator
 {
 using autoware::vehicle_info_utils::VehicleInfo;
 
+/**
+ * @brief Runs a set of validator plugins against each candidate trajectory.
+ */
 class TrajectoryValidator
 {
 public:
+  /**
+   * @brief Constructs the validator with the given plugin set.
+   * @param plugins Validator plugins to run against each trajectory.
+   */
   explicit TrajectoryValidator(std::vector<std::shared_ptr<plugin::ValidatorInterface>> plugins)
   : plugins_(std::move(plugins))
   {
   }
 
+  /**
+   * @brief Forwards updated parameters to all plugins.
+   * @param params Latest parameter values.
+   */
   void update_parameters(const validator::Params & params) const
   {
     for (const auto & plugin : plugins_) {
       plugin->update_parameters(params);
     }
   }
 
+  /**
+   * @brief Evaluates all plugins against every trajectory and returns a validation report.
+   * @param input_trajectories Candidate trajectories to validate.
+   * @param context Current world state snapshot.
+   */
   [[nodiscard]] TrajectoryValidatorReport process(
     const autoware_internal_planning_msgs::msg::CandidateTrajectories & input_trajectories,
     const ValidatorContext & context) const;

planning/autoware_trajectory_validator/include/autoware/trajectory_validator/detail/trajectory_validator_report.hpp

@@ -27,6 +27,7 @@
 namespace autoware::trajectory_validator
 {
 
+/** @brief Feasibility result of a single plugin for a single trajectory. */
 struct PluginEvaluation
 {
   std::string plugin_name;
@@ -35,18 +36,21 @@ struct PluginEvaluation
   std::string reason;
 };
 
+/** @brief Aggregated plugin evaluations for a single generator's trajectory. */
 struct EvaluationTable
 {
   std::string generator_id;
   std::vector<PluginEvaluation> plugin_evaluations;
 
+  /** @brief Returns true if every plugin passed or is in shadow mode. */
   [[nodiscard]] bool all_acceptable() const
   {
     return std::all_of(plugin_evaluations.begin(), plugin_evaluations.end(), [](const auto & e) {
       return e.is_feasible || e.is_shadow_mode;
     });
   }
 
+  /** @brief Returns true if every plugin passed, ignoring shadow mode. */
   [[nodiscard]] bool all_feasible() const
   {
     return std::all_of(plugin_evaluations.begin(), plugin_evaluations.end(), [](const auto & e) {
@@ -55,13 +59,7 @@ struct EvaluationTable
   }
 };
 
-/**
- * @brief Final opaque result structure returned by the validation stage.
- * CONTRACT FOR ROS NODE ADAPTER:
- * The Node MUST iterate over `evaluation_tables` post-process to:
- * 1. Emit `RCLCPP_WARN_THROTTLE` for any `!evaluation.is_feasible`.
- * 2. Update the `diagnostics_interface_` per plugin using the final evaluation states.
- */
+/** @brief Result returned by TrajectoryValidator::process. */
 struct TrajectoryValidatorReport
 {
   autoware_internal_planning_msgs::msg::CandidateTrajectories valid_trajectories;

planning/autoware_trajectory_validator/include/autoware/trajectory_validator/detail/validator_context.hpp

@@ -27,10 +27,7 @@
 namespace autoware::trajectory_validator
 {
 
-/**
- * @brief A read-only snapshot of the world state for a single validation stage execution.
- * Callees receive it by `const &` and must not mutate fields.
- */
+/** @brief World state snapshot passed to each validator plugin. */
 struct ValidatorContext
 {
   nav_msgs::msg::Odometry::ConstSharedPtr odometry;

planning/autoware_trajectory_validator/include/autoware/trajectory_validator/trajectory_selector_node.hpp

@@ -43,28 +43,43 @@ using autoware_perception_msgs::msg::PredictedObjects;
 using geometry_msgs::msg::AccelWithCovarianceStamped;
 using nav_msgs::msg::Odometry;
 
+/**
+ * @brief Concatenates candidate trajectories from multiple planners, validates them, and
+ * publishes the surviving set.
+ */
 class TrajectorySelectorNode : public rclcpp::Node
 {
 public:
+  /**
+   * @brief Constructs the node, declares parameters, and initialises all components.
+   * @param node_options ROS2 node options.
+   */
   explicit TrajectorySelectorNode(const rclcpp::NodeOptions & node_options);
 
 private:
-  /**
-   * @brief Initialise the node's subscribers.
-   */
+  /** @brief Creates all subscriptions. */
   void subscribers();
 
-  /**
-   * @brief Initialise the node's publishers.
-   */
+  /** @brief Creates all publishers and initialises the time keeper. */
   void publishers();
 
+  /**
+   * @brief Converts and stores the received lanelet map.
+   * @param msg Binary lanelet map message.
+   */
   void map_callback(const LaneletMapBin::ConstSharedPtr msg);
 
+  /**
+   * @brief Forwards incoming candidate trajectories to the concatenator.
+   * @param msg Incoming candidate trajectories message.
+   */
   void on_trajectories(const CandidateTrajectories::ConstSharedPtr msg);
 
+  /** @brief Concatenates buffered trajectories, validates them, and publishes the result. */
   void on_timer();
 
+  /** @brief Collects the latest sensor data needed for validation; returns an error string if any
+   * mandatory input is unavailable. */
   tl::expected<trajectory_validator::FilterContext, std::string> take_validator_data();
 
   std::unique_ptr<trajectory_concatenator::TrajectoryConcatenatorInterface> concatenator_ptr_;

planning/autoware_trajectory_validator/include/autoware/trajectory_validator/trajectory_validator_interface.hpp

@@ -58,63 +58,94 @@ using autoware_utils_diagnostics::DiagnosticsInterface;
 using geometry_msgs::msg::AccelWithCovarianceStamped;
 using nav_msgs::msg::Odometry;
 
+/**
+ * @brief ROS2 adapter for TrajectoryValidator: manages plugin loading, parameter updates,
+ * diagnostics, and debug publishing.
+ */
 class TrajectoryValidatorInterface
 {
 public:
+  /**
+   * @brief Loads plugins declared in the parameter lists and initialises all publishers.
+   * @param node ROS2 node used for publisher creation and logging.
+   * @param node_parameters_interface Parameter interface for declaring and reading parameters.
+   * @param vehicle_info Ego vehicle dimensions forwarded to each plugin.
+   * @param time_keeper Shared time keeper for processing time tracking.
+   */
   TrajectoryValidatorInterface(
     rclcpp::Node & node,
     rclcpp::node_interfaces::NodeParametersInterface::SharedPtr node_parameters_interface,
     vehicle_info_utils::VehicleInfo vehicle_info,
     std::shared_ptr<autoware_utils_debug::TimeKeeper> time_keeper);
 
+  /**
+   * @brief Runs all plugins against the input trajectories and returns the feasible subset.
+   * @param input_trajectories Candidate trajectories to validate.
+   * @param context Current world state snapshot.
+   */
   CandidateTrajectories validate_trajectories(
     const CandidateTrajectories & input_trajectories, const ValidatorContext & context);
 
 private:
+  /** @brief Creates the debug publisher. */
   void publishers();
 
+  /** @brief Reloads parameters from the parameter server if they have changed. */
   void update_parameters();
 
+  /**
+   * @brief Loads a single plugin by class name and configures it.
+   * @param name Plugin class name to load.
+   * @param is_shadow_mode If true, plugin results are logged but not enforced.
+   */
   void load_metric(const std::string & name, const bool is_shadow_mode = false);
 
+  /**
+   * @brief Updates the diagnostics status based on the number of feasible trajectories.
+   * @param input_trajectories Original input trajectories (used for total count).
+   * @param num_feasible_trajectories Number of trajectories that passed all plugins.
+   */
   void update_diagnostic(
     const CandidateTrajectories & input_trajectories, const size_t num_feasible_trajectories);
 
   /**
-   * @brief Publishes validation reports
-   * @param reports Validation reports to publish
+   * @brief Publishes the validation report array.
+   * @param reports Per-trajectory validation reports to publish.
    */
   void publish_validation_reports(const std::vector<ValidationReport> & reports);
 
   /**
-   * @brief Publish the union of all debug information.
+   * @brief Publishes all debug outputs: markers, report text, and processing times.
+   * @param evaluation_tables Per-trajectory plugin evaluation results.
+   * @param processing_time Per-plugin elapsed time in milliseconds.
+   * @param marker_pose Pose used to position text markers in RViz.
    */
   void publish_debug(
     const std::vector<EvaluationTable> & evaluation_tables,
     const std::unordered_map<std::string, double> & processing_time,
     const geometry_msgs::msg::Pose & marker_pose);
 
-  /**
-   * @brief Publish each plugin's debug markers.
-   */
+  /** @brief Publishes each plugin's accumulated debug markers. */
   void publish_plugins_debug_markers() const;
 
   /**
-   * @brief Publish each plugin's filtering report in a single string stamped marker.
+   * @brief Publishes a text marker summarising how many trajectories each plugin filtered.
+   * @param evaluation_tables Per-trajectory plugin evaluation results.
+   * @param marker_pose Pose used to position the text marker in RViz.
    */
   void publish_plugins_report_text(
     const std::vector<EvaluationTable> & evaluation_tables,
     const geometry_msgs::msg::Pose & marker_pose);
-  /**
 
-   * @brief Publish each plugin's processing time as scalar value.
-   * @param processing_time Map of plugin name -> elapsed time in [ms].
+  /**
+   * @brief Publishes each plugin's processing time as a scalar stamped value.
+   * @param processing_time Per-plugin elapsed time in milliseconds.
    */
   void publish_processing_time(const std::unordered_map<std::string, double> & processing_time);
 
   /**
-   * @brief Publish each plugin's processing time in a single string stamped marker.
-   * @param processing_time Map of plugin name -> elapsed time in [ms].
+   * @brief Publishes all plugin processing times as a single text marker.
+   * @param processing_time Per-plugin elapsed time in milliseconds.
    */
   void publish_processing_time_text(
     const std::unordered_map<std::string, double> & processing_time);