Skip to content

Commit 16bba47

Browse files
MARIANOCEREDAMARIANOCEREDA
authored
Improve docstring of the semantic_components for consistency (#3338)
1 parent 3839ae5 commit 16bba47

9 files changed

Lines changed: 127 additions & 79 deletions

‎controller_interface/include/semantic_components/force_torque_sensor.hpp‎

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,9 @@ namespace semantic_components
2929
class ForceTorqueSensor : public SemanticComponentInterface<geometry_msgs::msg::Wrench>
3030
{
3131
public:
32-
/// Constructor for "standard" 6D FTS
32+
/**
33+
* @brief Constructor for "standard" 6D FTS
34+
*/
3335
explicit ForceTorqueSensor(const std::string & name)
3436
: SemanticComponentInterface(
3537
name,
@@ -45,9 +47,10 @@ class ForceTorqueSensor : public SemanticComponentInterface<geometry_msgs::msg::
4547
data_.fill(std::numeric_limits<double>::quiet_NaN());
4648
}
4749

48-
/// Constructor for 6D FTS with custom interface names.
4950
/**
50-
* Constructor for 6D FTS with custom interface names or FTS with less then six measurement axes,
51+
* @brief Constructor for 6D FTS with custom interface names.
52+
*
53+
* Constructor for 6D FTS with custom interface names or FTS with less than six measurement axes,
5154
* e.g., 1D and 2D force load cells.
5255
* For non existing axes interface is empty string, i.e., ("");
5356
*
@@ -83,11 +86,12 @@ class ForceTorqueSensor : public SemanticComponentInterface<geometry_msgs::msg::
8386
check_and_add_interface(interface_torque_z, 5);
8487
}
8588

86-
/// Return forces.
8789
/**
90+
* @brief Return forces.
91+
*
8892
* Return forces of a FTS.
8993
*
90-
* \return array of size 3 with force values (x, y, z).
94+
* @return array of size 3 with force values (x, y, z).
9195
*/
9296
std::array<double, 3> get_forces() const
9397
{
@@ -97,11 +101,12 @@ class ForceTorqueSensor : public SemanticComponentInterface<geometry_msgs::msg::
97101
return forces;
98102
}
99103

100-
/// Return torque.
101104
/**
105+
* @brief Return torque.
106+
*
102107
* Return torques of a FTS.
103108
*
104-
* \return array of size 3 with torque values (x, y, z).
109+
* @return array of size 3 with torque values (x, y, z).
105110
*/
106111
std::array<double, 3> get_torques() const
107112
{
@@ -111,13 +116,15 @@ class ForceTorqueSensor : public SemanticComponentInterface<geometry_msgs::msg::
111116
return torques;
112117
}
113118

114-
/// Return Wrench message with forces and torques.
115119
/**
120+
* @brief Return Wrench message with forces and torques.
121+
*
116122
* Constructs and return a wrench message from the current values.
117123
* The method assumes that the interface names on the construction are in the following order:
118124
* force X, force Y, force Z, torque X, torque Y, torque Z.
119125
*
120-
* \return wrench message from values;
126+
* @param[out] message Wrench message from values
127+
* @return always returns true
121128
*/
122129
bool get_values_as_message(geometry_msgs::msg::Wrench & message) const
123130
{
@@ -156,9 +163,13 @@ class ForceTorqueSensor : public SemanticComponentInterface<geometry_msgs::msg::
156163
}
157164
}
158165

159-
/// Array to store the data of the FT sensors
166+
/**
167+
* @brief Array to store the data of the FT sensors
168+
*/
160169
mutable std::array<double, 6> data_;
161-
/// Vector with existing axes for sensors with less then 6D axes.
170+
/**
171+
* @brief Array with existing axes for sensors with less than 6D axes.
172+
*/
162173
std::array<bool, 6> existing_axes_;
163174
};
164175

‎controller_interface/include/semantic_components/gps_sensor.hpp‎

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@ class GPSSensor : public SemanticComponentInterface<sensor_msgs::msg::NavSatFix>
5757
}
5858

5959
/**
60-
* Return GPS's status e.g. fix/no_fix
60+
* @brief Return GPS's status e.g. fix/no_fix
6161
*
62-
* \return Status
62+
* @return Status
6363
*/
6464
int8_t get_status() const
6565
{
@@ -72,9 +72,9 @@ class GPSSensor : public SemanticComponentInterface<sensor_msgs::msg::NavSatFix>
7272
}
7373

7474
/**
75-
* Return service used by GPS e.g. fix/no_fix
75+
* @brief Return service used by GPS e.g. fix/no_fix
7676
*
77-
* \return Service
77+
* @return Service
7878
*/
7979
uint16_t get_service() const
8080
{
@@ -87,9 +87,9 @@ class GPSSensor : public SemanticComponentInterface<sensor_msgs::msg::NavSatFix>
8787
}
8888

8989
/**
90-
* Return latitude reported by a GPS
90+
* @brief Return latitude reported by a GPS
9191
*
92-
* \return Latitude.
92+
* @return Latitude.
9393
*/
9494
double get_latitude() const
9595
{
@@ -102,9 +102,9 @@ class GPSSensor : public SemanticComponentInterface<sensor_msgs::msg::NavSatFix>
102102
}
103103

104104
/**
105-
* Return longitude reported by a GPS
105+
* @brief Return longitude reported by a GPS
106106
*
107-
* \return Longitude.
107+
* @return Longitude.
108108
*/
109109
double get_longitude() const
110110
{
@@ -117,9 +117,9 @@ class GPSSensor : public SemanticComponentInterface<sensor_msgs::msg::NavSatFix>
117117
}
118118

119119
/**
120-
* Return altitude reported by a GPS
120+
* @brief Return altitude reported by a GPS
121121
*
122-
* \return Altitude.
122+
* @return Altitude.
123123
*/
124124
double get_altitude() const
125125
{
@@ -132,9 +132,9 @@ class GPSSensor : public SemanticComponentInterface<sensor_msgs::msg::NavSatFix>
132132
}
133133

134134
/**
135-
* Return covariance reported by a GPS.
135+
* @brief Return covariance reported by a GPS.
136136
*
137-
* \return Covariance array.
137+
* @return Covariance array.
138138
*/
139139
template <
140140
typename U = void,
@@ -160,7 +160,10 @@ class GPSSensor : public SemanticComponentInterface<sensor_msgs::msg::NavSatFix>
160160
}
161161

162162
/**
163-
* Fills a NavSatFix message from the current values.
163+
* @brief Fills a NavSatFix message from the current values.
164+
*
165+
* @param[out] message NavSatFix message from values
166+
* @return always returns true
164167
*/
165168
bool get_values_as_message(sensor_msgs::msg::NavSatFix & message)
166169
{

‎controller_interface/include/semantic_components/imu_sensor.hpp‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,12 @@ class IMUSensor : public SemanticComponentInterface<sensor_msgs::msg::Imu>
4242
{name + "/" + "linear_acceleration.z"}})
4343
{
4444
}
45-
/// Return orientation.
4645
/**
46+
* @brief Return orientation.
47+
*
4748
* Return orientation reported by an IMU
4849
*
49-
* \return Array of size 4 with orientation quaternion (x,y,z,w).
50+
* @return Array of size 4 with orientation quaternion (x,y,z,w).
5051
*/
5152
std::array<double, 4> get_orientation() const
5253
{
@@ -56,11 +57,12 @@ class IMUSensor : public SemanticComponentInterface<sensor_msgs::msg::Imu>
5657
return orientation;
5758
}
5859

59-
/// Return angular velocity.
6060
/**
61+
* @brief Return angular velocity.
62+
*
6163
* Return angular velocity reported by an IMU
6264
*
63-
* \return array of size 3 with angular velocity values (x, y, z).
65+
* @return array of size 3 with angular velocity values (x, y, z).
6466
*/
6567
std::array<double, 3> get_angular_velocity() const
6668
{
@@ -70,11 +72,12 @@ class IMUSensor : public SemanticComponentInterface<sensor_msgs::msg::Imu>
7072
return angular_velocity;
7173
}
7274

73-
/// Return linear acceleration.
7475
/**
76+
* @brief Return linear acceleration.
77+
*
7578
* Return linear acceleration reported by an IMU
7679
*
77-
* \return array of size 3 with linear acceleration values (x, y, z).
80+
* @return array of size 3 with linear acceleration values (x, y, z).
7881
*/
7982
std::array<double, 3> get_linear_acceleration() const
8083
{
@@ -84,10 +87,12 @@ class IMUSensor : public SemanticComponentInterface<sensor_msgs::msg::Imu>
8487
return linear_acceleration;
8588
}
8689

87-
/// Return Imu message with orientation, angular velocity and linear acceleration
8890
/**
91+
* @brief Return Imu message with orientation, angular velocity and linear acceleration
92+
*
8993
* Constructs and return a IMU message from the current values.
90-
* \return imu message from values;
94+
* @param[out] message IMU message from values
95+
* @return always returns true
9196
*/
9297
bool get_values_as_message(sensor_msgs::msg::Imu & message) const
9398
{

‎controller_interface/include/semantic_components/led_rgb_device.hpp‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,15 @@ class LedRgbDevice : public SemanticComponentCommandInterface<std_msgs::msg::Col
2727
{
2828
public:
2929
/**
30-
* Constructor for a LED RGB device with interface names set based on device name.
30+
* @brief Constructor for an LED RGB device with interface names set based on device name.
31+
*
3132
* The constructor sets the command interface names to "<name>/interface_r",
3233
* "<name>/interface_g", "<name>/interface_b".
3334
*
34-
* \param[in] name name of the LED device, used as a prefix for the command interface names
35-
* \param[in] interface_r name of the command interface for the red channel
36-
* \param[in] interface_g name of the command interface for the green channel
37-
* \param[in] interface_b name of the command interface for the blue channel
35+
* @param[in] name name of the LED device, used as a prefix for the command interface names
36+
* @param[in] interface_r name of the command interface for the red channel
37+
* @param[in] interface_g name of the command interface for the green channel
38+
* @param[in] interface_b name of the command interface for the blue channel
3839
*/
3940
explicit LedRgbDevice(
4041
const std::string & name, const std::string & interface_r, const std::string & interface_g,
@@ -44,17 +45,17 @@ class LedRgbDevice : public SemanticComponentCommandInterface<std_msgs::msg::Col
4445
{
4546
}
4647

47-
/// Set LED states from ColorRGBA message
48-
4948
/**
49+
* @brief Set LED states from ColorRGBA message
50+
*
5051
* Set the values of the LED RGB device from a ColorRGBA message.
5152
*
52-
* \details Sets the values of the red, green, and blue channels from the message.
53+
* @details Sets the values of the red, green, and blue channels from the message.
5354
* If any of the values are out of the range [0, 1], the function fails and returns false.
5455
*
55-
* \param[in] message ColorRGBA message
56+
* @param[in] message ColorRGBA message
5657
*
57-
* \return true if all values were set, false otherwise
58+
* @return true if all values were set, false otherwise
5859
*/
5960
bool set_values_from_message(const std_msgs::msg::ColorRGBA & message) override
6061
{

‎controller_interface/include/semantic_components/magnetic_field_sensor.hpp‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,11 @@ class MagneticFieldSensor : public SemanticComponentInterface<sensor_msgs::msg::
3232
{
3333
}
3434

35-
/// Returns values as sensor_msgs::msg::MagneticField
3635
/**
37-
* \return MagneticField message from values
36+
* @brief Returns values as sensor_msgs::msg::MagneticField
37+
*
38+
* @param[out] message MagneticField message from values
39+
* @return always returns true
3840
*/
3941
bool get_values_as_message(sensor_msgs::msg::MagneticField & message)
4042
{
@@ -64,7 +66,9 @@ class MagneticFieldSensor : public SemanticComponentInterface<sensor_msgs::msg::
6466
}
6567
}
6668

67-
// Array to store the data of the magnetic field sensor
69+
/**
70+
* @brief Array to store the data of the magnetic field sensor
71+
*/
6872
std::array<double, 3> data_{{0.0, 0.0, 0.0}};
6973
};
7074

‎controller_interface/include/semantic_components/pose_sensor.hpp‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,9 @@ namespace semantic_components
2828
class PoseSensor : public SemanticComponentInterface<geometry_msgs::msg::Pose>
2929
{
3030
public:
31-
/// Constructor for a standard pose sensor with interface names set based on sensor name.
31+
/**
32+
* @brief Constructor for a standard pose sensor with interface names set based on sensor name.
33+
*/
3234
explicit PoseSensor(const std::string & name)
3335
: SemanticComponentInterface(
3436
name, {{name + '/' + "position.x"},
@@ -40,11 +42,12 @@ class PoseSensor : public SemanticComponentInterface<geometry_msgs::msg::Pose>
4042
{name + '/' + "orientation.w"}})
4143
{
4244
}
43-
/// Update and return position.
44-
/*!
45+
/**
46+
* @brief Update and return position.
47+
*
4548
* Update and return current pose position from state interfaces.
4649
*
47-
* \return Array of position coordinates.
50+
* @return Array of position coordinates.
4851
*/
4952
std::array<double, 3> get_position() const
5053
{
@@ -54,11 +57,12 @@ class PoseSensor : public SemanticComponentInterface<geometry_msgs::msg::Pose>
5457
return position;
5558
}
5659

57-
/// Update and return orientation
58-
/*!
60+
/**
61+
* @brief Update and return orientation
62+
*
5963
* Update and return current pose orientation from state interfaces.
6064
*
61-
* \return Array of orientation coordinates in xyzw convention.
65+
* @return Array of orientation coordinates in xyzw convention.
6266
*/
6367
std::array<double, 4> get_orientation() const
6468
{
@@ -68,9 +72,13 @@ class PoseSensor : public SemanticComponentInterface<geometry_msgs::msg::Pose>
6872
return orientation;
6973
}
7074

71-
/// Fill pose message with current values.
7275
/**
76+
* @brief Fill pose message with current values.
77+
*
7378
* Fill a pose message with current position and orientation from the state interfaces.
79+
*
80+
* @param[out] message Pose message from values
81+
* @return always returns true
7482
*/
7583
bool get_values_as_message(geometry_msgs::msg::Pose & message) const
7684
{
@@ -106,7 +114,9 @@ class PoseSensor : public SemanticComponentInterface<geometry_msgs::msg::Pose>
106114
}
107115
}
108116

109-
/// Array to store the data of the pose sensor
117+
/**
118+
* @brief Array to store the data of the pose sensor
119+
*/
110120
mutable std::array<double, 7> data_{{0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0}};
111121
};
112122

‎controller_interface/include/semantic_components/range_sensor.hpp‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,9 @@ class RangeSensor : public SemanticComponentInterface<sensor_msgs::msg::Range>
3232
{
3333
}
3434
/**
35-
* Return Range reported by a sensor
35+
* @brief Return Range reported by a sensor
3636
*
37-
* \return value of the range in meters
37+
* @return value of the range in meters
3838
*/
3939
float get_range() const
4040
{
@@ -46,10 +46,12 @@ class RangeSensor : public SemanticComponentInterface<sensor_msgs::msg::Range>
4646
return std::numeric_limits<float>::quiet_NaN();
4747
}
4848

49-
/// Return Range message with range in meters
5049
/**
50+
* @brief Return Range message with range in meters
51+
*
5152
* Constructs and return a Range message from the current values.
52-
* \return Range message from values;
53+
* @param[out] message Range message from values
54+
* @return always returns true
5355
*/
5456
bool get_values_as_message(sensor_msgs::msg::Range & message) const
5557
{

0 commit comments

Comments
 (0)