Address peer review comments

Signed-off-by: Michel Hidalgo <[email protected]>

proto/gz/msgs/dvl_beam_state.proto

@@ -23,7 +23,7 @@ option java_outer_classname = "DVLBeamStateProtos";
 /// \ingroup gz.msgs
 /// \interface DVLBeamState
 /// \brief State of some acoustic beam in a Doppler Velocity Log sensor. Each beam, when locked,
-/// estimates the distance to the reflecting target as well as its velocity in some reference 
+/// estimates the distance to the reflecting target as well as its velocity in some reference
 /// frame. Some additional attributes may also be available.
 
 import "gz/msgs/dvl_kinematic_estimate.proto";
@@ -34,18 +34,22 @@ message DVLBeamState
  /// \brief Beam ID.
  int32 id = 1;
 
- /// \brief Beam velocity estimate.
+ /// \brief Beam velocity estimate, measured along
+ /// its axis, in meters per second.
  DVLKinematicEstimate velocity = 2;
 
- /// \brief Beam range estimate.
+ /// \brief Beam range estimate, in meters.
  DVLRangeEstimate range = 3;
 
  /// \brief Beam signal strength indicator.
  double rssi = 4;
 
- /// \brief Measured background noise spectral density.
+ /// \brief Measured background noise spectral density,
+ /// in watts per hertz.
  double nsd = 5;
 
- /// \brief Whether beam is locked or not.
+ /// \brief Whether beam is locked to its target or not.
+ /// A beam is said to be locked when it can reliably
+ /// measure signal reflections.
  bool locked = 6;
 }

proto/gz/msgs/dvl_kinematic_estimate.proto

@@ -31,12 +31,15 @@ import "gz/msgs/vector3d.proto";
 
 message DVLKinematicEstimate
 {
+ /// \brief Frames of reference (incl. conventions)
  enum ReferenceType
  {
+ /// \brief Unspecific frame of reference.
  DVL_REFERENCE_UNSPECIFIED = 0;
+ /// \brief Earth bound frame of reference (typically ENU).
  DVL_REFERENCE_EARTH = 1;
+ /// \brief Ship bound frame of reference (typically FSK).
  DVL_REFERENCE_SHIP = 2;
- DVL_REFERENCE_BEAM = 3;
  };
  /// \brief Estimate frame of reference (incl. conventions).
  ReferenceType reference = 1;

proto/gz/msgs/dvl_tracking_target.proto

@@ -31,18 +31,22 @@ import "gz/msgs/dvl_range_estimate.proto";
 
 message DVLTrackingTarget
 {
+ /// \brief Target types
  enum TargetType
  {
+ /// \brief Unspecific target type.
  DVL_TARGET_UNSPECIFIED = 0;
+ /// \brief Bottom ground (ie. solid) target.
  DVL_TARGET_BOTTOM = 1;
+ /// \brief Water mass layer (ie. fluid) target.
  DVL_TARGET_WATER_MASS = 2;
  };
  /// \brief Type of target used for tracking.
  TargetType type = 1;
 
- /// \brief Target range (or distance).
- DVLRangeEstimate range = 3;
+ /// \brief Target range (or distance), in meters
+ DVLRangeEstimate range = 2;
 
- /// \brief Target position estimate.
- DVLKinematicEstimate position = 2;
+ /// \brief Target position estimate, in meters.
+ DVLKinematicEstimate position = 3;
 }

proto/gz/msgs/dvl_velocity_tracking.proto

@@ -22,7 +22,7 @@ option java_outer_classname = "DVLVelocityTrackingProtos";
 
 /// \ingroup gz.msgs
 /// \interface DVLVelocityTracking
-/// \brief Velocity tracking estimates from a Doppler Velocity Log sensor. 
+/// \brief Velocity tracking estimates from a Doppler Velocity Log sensor.
 /// Doppler velocity logs are used by the maritime community to track the velocity
 /// of a vessel with respect to some (reflecting) target.
 
@@ -36,10 +36,14 @@ message DVLVelocityTracking
  /// \brief Message header.
  Header header = 1;
 
+ /// \brief DVL types.
  enum DVLType
  {
+ /// \brief Unspecific DVL type.
  DVL_TYPE_UNSPECIFIED = 0;
+ /// \brief Piston DVLs.
  DVL_TYPE_PISTON = 1;
+ /// \brief Phased array DVLs.
  DVL_TYPE_PHASED_ARRAY = 2;
  };
  /// \brief Type of DVL.
@@ -48,7 +52,8 @@ message DVLVelocityTracking
  /// \brief Locked on target.
  DVLTrackingTarget target = 3;
 
- /// \brief Estimated velocity.
+ /// \brief Estimated velocity of either target or sensor
+ /// w.r.t. the specified frame, in meters per second.
  DVLKinematicEstimate velocity = 4;
 
  /// \brief Tracking beams' state.