Standardize Doxygen parameter formatting for systems O-Z (#2212)

* standardize system parameter doxygen for plugins O-Z
* 80 chars
* Update TrackedVehicle.hh
* fix lint
* gcc warning about multi-line comment
Signed-off-by: Mabel Zhang <[email protected]>

src/systems/buoyancy_engine/BuoyancyEngine.hh

@@ -74,16 +74,19 @@ namespace systems
   /// gz sim buoyancy_engine.sdf
   /// ```
   /// Enter the following in a separate terminal:
-  /// ```
-  /// gz topic -t /model/buoyant_box/buoyancy_engine/ -m gz.msgs.Double \
-  ///    -p "data: 0.003"
-  /// ```
+  /** ```
+      gz topic -t /model/buoyant_box/buoyancy_engine/ -m gz.msgs.Double \
+         -p "data: 0.003"
+      ```
+  **/
   /// to see the box float up.
-  /// ```
-  /// gz topic -t /model/buoyant_box/buoyancy_engine/ -m gz.msgs.Double \
-  ///    -p "data: 0.001"
-  /// ```
+  /** ```
+      gz topic -t /model/buoyant_box/buoyancy_engine/ -m gz.msgs.Double \
+         -p "data: 0.001"
+      ```
+  **/
   /// to see the box go down.
+  ///
   /// To see the current volume enter:
   /// ```
   /// gz topic -t /model/buoyant_box/buoyancy_engine/current_volume -e

src/systems/odometry_publisher/OdometryPublisher.hh

@@ -36,44 +36,44 @@ namespace systems
   /// order to periodically publish 2D or 3D odometry data in the form of
   /// gz::msgs::Odometry messages.
   ///
-  /// # System Parameters
+  /// ## System Parameters
   ///
-  /// `<odom_frame>`: Name of the world-fixed coordinate frame for the
+  /// - `<odom_frame>`: Name of the world-fixed coordinate frame for the
   //  odometry message. This element is optional, and the default value
   /// is `{name_of_model}/odom`.
   ///
-  /// `<robot_base_frame>`: Name of the coordinate frame rigidly attached
+  /// - `<robot_base_frame>`: Name of the coordinate frame rigidly attached
   /// to the mobile robot base. This element is optional, and the default
   /// value is `{name_of_model}/base_footprint`.
   ///
-  /// `<odom_publish_frequency>`: Odometry publication frequency. This
+  /// - `<odom_publish_frequency>`: Odometry publication frequency. This
   /// element is optional, and the default value is 50Hz.
   ///
-  /// `<odom_topic>`: Custom topic on which this system will publish odometry
+  /// - `<odom_topic>`: Custom topic on which this system will publish odometry
   /// messages. This element is optional, and the default value is
   /// `/model/{name_of_model}/odometry`.
   ///
-  /// `<odom_covariance_topic>`: Custom topic on which this system will publish
-  /// odometry with covariance messages. This element is optional, and the
-  /// default value is `/model/{name_of_model}/odometry_with_covariance`.
+  /// - `<odom_covariance_topic>`: Custom topic on which this system will
+  /// publish odometry with covariance messages. This element is optional, and
+  /// the default value is `/model/{name_of_model}/odometry_with_covariance`.
   ///
-  /// `<tf_topic>`: Custom topic on which this system will publish the
+  /// - `<tf_topic>`: Custom topic on which this system will publish the
   /// transform from `odom_frame` to `robot_base_frame`. This element is
   /// optional, and the default value is `/model/{name_of_model}/pose`.
   ///
-  /// `<dimensions>`: Number of dimensions to represent odometry. Only 2 and 3
+  /// - `<dimensions>`: Number of dimensions to represent odometry. Only 2 and 3
   /// dimensional spaces are supported. This element is optional, and the
   /// default value is 2.
   ///
-  /// `<xyz_offset>`: Position offset relative to the body fixed frame, the
+  /// - `<xyz_offset>`: Position offset relative to the body fixed frame, the
   /// default value is 0 0 0. This offset will be added to the odometry
   /// message.
   ///
-  /// `<rpy_offset>`: Rotation offset relative to the body fixed frame, the
+  /// - `<rpy_offset>`: Rotation offset relative to the body fixed frame, the
   /// default value is 0 0 0. This offset will be added to the odometry
-  ///  message.
+  /// message.
   ///
-  /// `<gaussian_noise>`: Standard deviation of the Gaussian noise to be added
+  /// - `<gaussian_noise>`: Standard deviation of the Gaussian noise to be added
   /// to pose and twist messages. This element is optional, and the default
   /// value is 0.
   class OdometryPublisher

src/systems/optical_tactile_plugin/OpticalTactilePlugin.hh

@@ -37,54 +37,52 @@ namespace systems
   ///
   /// It requires that contact sensor and depth camera be placed in at least
   /// one link on the model on which this plugin is attached.
-  /// TODO:
+  ///
+  /// \todo(anyone)
   /// Currently, the contacts returned from the physics engine (which tends to
   /// be sparse) and the normal forces separately computed from the depth
   /// camera (which is dense, resolution adjustable) are disjoint. It is
   /// left as future work to combine the two sets of data.
   ///
-  /// Parameters:
+  /// ## System Parameters
   ///
-  /// <enabled> Set this to true so the plugin works from the start and
-  ///           doesn't need to be enabled. This element is optional, and the
-  ///           default value is true.
+  /// - `<enabled>`: Set this to true so the plugin works from the start and
+  /// doesn't need to be enabled. This element is optional, and the
+  /// default value is true.
   ///
-  /// <namespace> Namespace for transport topics/services. If there are more
-  ///             than one optical tactile plugins, their namespaces should
-  ///             be different.
-  ///             This element is optional, and the default value is
-  ///             "optical_tactile_sensor".
-  ///             /<namespace>/enable : Service used to enable and disable the
-  ///                                   plugin.
-  ///             /<namespace>/normal_forces : Topic where a message is
-  ///                                          published each time the
-  ///                                          normal forces are computed
+  /// - `<namespace>`: Namespace for transport topics/services. If there are
+  /// more than one optical tactile plugins, their namespaces should
+  /// be different. This element is optional, and the default value is
+  /// "optical_tactile_sensor".
+  ///   - `/<namespace>/enable`: Service used to enable and disable the plugin.
+  ///   - `/<namespace>/normal_forces`: Topic where a message is
+  ///     published each time the normal forces are computed
   ///
-  /// <visualization_resolution> Number n of pixels to skip when visualizing
-  ///                            the forces. One vector representing a normal
-  ///                            force is computed for every nth pixel. This
-  ///                            element must be positive and it is optional.
-  ///                            The default value is 30.
+  /// - `<visualization_resolution>`: Number n of pixels to skip when
+  /// visualizing the forces. One vector representing a normal
+  /// force is computed for every nth pixel. This
+  /// element must be positive and it is optional.
+  /// The default value is 30.
   ///
-  /// <force_length> Length in meters of the forces visualized if
-  ///                <visualize_forces> is set to true. This parameter is
-  ///                optional, and the default value is 0.01.
+  /// - `<force_length>`: Length in meters of the forces visualized if
+  /// <visualize_forces> is set to true. This parameter is
+  /// optional, and the default value is 0.01.
   ///
-  /// <extended_sensing> Extended sensing distance in meters. The sensor will
-  ///                    output data coming from its collision geometry plus
-  ///                    this distance. This element is optional, and the
-  ///                    default value is 0.001.
+  /// - `<extended_sensing>`: Extended sensing distance in meters. The sensor
+  /// will output data coming from its collision geometry plus
+  /// this distance. This element is optional, and the
+  /// default value is 0.001.
   ///
-  /// <visualize_sensor> Whether to visualize the sensor or not. This element
-  ///                    is optional, and the default value is false.
+  /// - `<visualize_sensor>`: Whether to visualize the sensor or not. This
+  /// element is optional, and the default value is false.
   ///
-  /// <visualize_contacts> Whether to visualize the contacts from the contact
-  ///                      sensor based on physics. This element is optional,
-  ///                      and the default value is false.
+  /// - `<visualize_contacts>`: Whether to visualize the contacts from the
+  /// contact sensor based on physics. This element is optional,
+  /// and the default value is false.
   ///
-  /// <visualize_forces> Whether to visualize normal forces computed from the
-  ///                    depth camera. This element is optional, and the
-  ///                    default value is false.
+  /// - `<visualize_forces>`: Whether to visualize normal forces computed from
+  /// the depth camera. This element is optional, and the
+  /// default value is false.
 
   class OpticalTactilePlugin :
     public System,

src/systems/particle_emitter/ParticleEmitter.hh

@@ -32,10 +32,10 @@ namespace systems
   class ParticleEmitterPrivate;
 
   /// \brief A system for running and managing particle emitters. A particle
-  /// emitter is defined using the <particle_emitter> SDF element.
+  /// emitter is defined using the `<particle_emitter>` SDF element.
   ///
   /// This system will create a transport subscriber for each
-  /// <particle_emitter> using the child <topic> name. If a <topic> is not
+  /// `<particle_emitter>` using the child `<topic>` name. If a `<topic>` is not
   /// specified, the following topic naming scheme will be used:
   /// `/model/{model_name}/link/{link_name}/particle_emitter/{emitter_name}/cmd`
   class ParticleEmitter

src/systems/performer_detector/PerformerDetector.hh

@@ -45,8 +45,9 @@ namespace systems
   /// PerformerDetector's region, which is also represented by an
   /// gz::math::AxisAlignedBox. When a performer is detected, the system
   /// publishes a gz.msgs.Pose message with the pose of the detected
-  /// performer with respect to the model containing the PerformerDetector. The
-  /// name and id fields of the Pose message will be set to the name and the
+  /// performer with respect to the model containing the PerformerDetector.
+  ///
+  /// The name and id fields of the Pose message will be set to the name and the
   /// entity of the detected performer respectively. The header of the Pose
   /// message contains the time stamp of detection. The `data` field of the
   /// header will contain the key "frame_id" with a value set to the name of
@@ -62,19 +63,22 @@ namespace systems
   /// The system does not assume that levels are enabled, but it does require
   /// performers to be specified.
   ///
-  /// ## System parameters
+  /// ## System Parameters
   ///
-  /// `<topic>`: Custom topic to be used for publishing when a performer is
+  /// - `<topic>`: Custom topic to be used for publishing when a performer is
   /// detected. If not set, the default topic with the following pattern would
   /// be used "/model/<model_name>/performer_detector/status". The topic type
   /// is gz.msgs.Pose
-  /// `<geometry>`: Detection region. Currently, only the `<box>` geometry is
+  ///
+  /// - `<geometry>`: Detection region. Currently, only the `<box>` geometry is
   /// supported. The position of the geometry is derived from the pose of the
   /// containing model.
-  /// `<pose>`: Additional pose offset relative to the parent model's pose.
+  ///
+  /// - `<pose>`: Additional pose offset relative to the parent model's pose.
   /// This pose is added to the parent model pose when computing the
   /// detection region. Only the position component of the `<pose>` is used.
-  /// `<header_data>`: Zero or more key-value pairs that will be
+  ///
+  /// - `<header_data>`: Zero or more key-value pairs that will be
   /// included in the header of the detection messages. A `<header_data>`
   /// element should have child `<key>` and `<value>` elements whose
   /// contents are interpreted as strings. Keys value pairs are stored in a

src/systems/physics/Physics.hh

@@ -64,9 +64,15 @@ namespace systems
 
   /// \class Physics Physics.hh gz/sim/systems/Physics.hh
   /// \brief Base class for a System.
-  /// Includes optional parameter : <include_entity_names>. When set
+  ///
+  /// ## System Parameters
+  ///
+  /// - `<include_entity_names>`: Optional. When set
   /// to false, the name of colliding entities is not populated in
-  /// the contacts. Remains true by default. Usage :
+  /// the contacts. Remains true by default.
+  ///
+  /// ## Example
+  ///
   /// ```
   ///  <plugin
   ///    filename="gz-sim-physics-system"

src/systems/python_system_loader/PythonSystemLoader.hh

@@ -55,14 +55,14 @@ namespace systems
 /// check if the corresponding method is implemented in the Python system and
 /// skip it if it's not found.
 ///
-/// See examples/scripts/python_api/systems/test_system.py for an example
+/// See `examples/scripts/python_api/systems/test_system.py` for an example
 ///
-/// ## Parameters
-/// * <module_name> : Name of python module to be loaded. The search path
+/// ## System Parameters
+/// * `<module_name>` : Name of python module to be loaded. The search path
 ///                   includes `GZ_SIM_SYSTEM_PLUGIN_PATH` as well as
 ///                   `PYTHONPATH`.
 ///
-/// The contents of the <plugin> tag will be available in the configure method
+/// The contents of the `<plugin>` tag will be available in the configure method
 /// of the Python system
 // TODO(azeey) Add ParameterConfigure
 class GZ_SIM_PYTHON_SYSTEM_LOADER_SYSTEM_HIDDEN PythonSystemLoader final

src/systems/rf_comms/RFComms.hh

@@ -38,31 +38,37 @@ namespace systems
   /// This communication model has been ported from:
   /// https://github.com/osrf/subt .
   ///
+  /// ## System Parameters
+  ///
   /// This system can be configured with the following SDF parameters:
   ///
-  /// * Optional parameters:
-  /// <range_config> Element used to capture the range configuration based on a
-  ///                log-normal distribution. This block can contain any of the
-  ///                next parameters:
-  ///    * <max_range>: Hard limit on range (meters). No communication will
-  ///                   happen beyond this range. Default is 50.
-  ///    * <fading_exponent>: Fading exponent used in the normal distribution.
-  ///                         Default is 2.5.
-  ///    * <l0>: Path loss at the reference distance (1 meter) in dBm.
-  ///            Default is 40.
-  ///    * <sigma>: Standard deviation of the normal distribution.
-  ///               Default is 10.
+  /// Optional parameters:
+  ///
+  /// - `<range_config>`: Element used to capture the range configuration based
+  ///   on a log-normal distribution. This block can contain any of the
+  ///   next parameters:
+  ///   - `<max_range>`: Hard limit on range (meters). No communication will
+  ///                    happen beyond this range. Default is 50.
+  ///   - `<fading_exponent>`: Fading exponent used in the normal distribution.
+  ///                          Default is 2.5.
+  ///   - `<l0>`: Path loss at the reference distance (1 meter) in dBm.
+  ///             Default is 40.
+  ///   - `<sigma>`: Standard deviation of the normal distribution.
+  ///                Default is 10.
+  ///
+  /// - `<radio_config>`: Element used to capture the radio configuration.
+  ///                     This block can contain any of the
+  ///                     next parameters:
+  ///   - `<capacity>`: Capacity of radio in bits-per-second.
+  ///                   Default is 54000000 (54 Mbps).
+  ///   - `<tx_power>`: Transmitter power in dBm. Default is 27dBm (500mW).
+  ///   - `<noise_floor>`: Noise floor in dBm.  Default is -90dBm.
+  ///   - `<modulation>`: Supported modulations: ["QPSK"]. Default is "QPSK".
   ///
-  /// <radio_config> Element used to capture the radio configuration.
-  ///                This block can contain any of the
-  ///                next parameters:
-  ///    * <capacity>: Capacity of radio in bits-per-second.
-  ///                  Default is 54000000 (54 Mbps).
-  ///    * <tx_power>: Transmitter power in dBm. Default is 27dBm (500mW).
-  ///    * <noise_floor>: Noise floor in dBm.  Default is -90dBm.
-  ///    * <modulation>: Supported modulations: ["QPSK"]. Default is "QPSK".
+  /// ## Example
   ///
   /// Here's an example:
+  /// ```
   /// <plugin
   ///   filename="gz-sim-rf-comms-system"
   ///   name="gz::sim::systems::RFComms">
@@ -79,6 +85,7 @@ namespace systems
   ///     <modulation>QPSK</modulation>
   ///   </radio_config>
   /// </plugin>
+  /// ```
   class RFComms
     : public comms::ICommsModel
   {

src/systems/sensors/Sensors.hh

@@ -40,14 +40,14 @@ namespace systems
   ///
   /// ## System Parameters
   ///
-  /// - `<render_engine>` Name of the render engine, such as 'ogre' or 'ogre2'.
-  /// - `<background_color>` Color used for the scene's background. This
+  /// - `<render_engine>`: Name of the render engine, such as "ogre" or "ogre2".
+  /// - `<background_color>`: Color used for the scene's background. This
   /// will override the background color specified in a world's SDF <scene>
   /// element. This background color is used by sensors, not the GUI.
-  /// - `<ambient_light>` Color used for the scene's ambient light. This
+  /// - `<ambient_light>`: Color used for the scene's ambient light. This
   /// will override the ambient value specified in a world's SDF <scene>
   /// element. This ambient light is used by sensors, not the GUI.
-  /// - `<disable_on_drained_battery>` Disable sensors if the model's
+  /// - `<disable_on_drained_battery>`: Disable sensors if the model's
   /// battery plugin charge reaches zero. Sensors that are in nested
   /// models are also affected.
   ///