Remove doxygen warnings (#4700, #5011) (#5016)

* Refs #21114: Remove doxygen warnings

Signed-off-by: eduponz <eduardoponz@eprosima.com>

* Refs #21114: Apply Miguel's suggestions

Signed-off-by: eduponz <eduardoponz@eprosima.com>

---------

Signed-off-by: eduponz <eduardoponz@eprosima.com>

include/fastdds/dds/core/policy/QosPolicies.hpp

@@ -2798,8 +2798,9 @@ class TransportConfigQos : public QosPolicy
     //! Thread settings for the builtin transports reception threads
     rtps::ThreadSettings builtin_transports_reception_threads_;
 
-    /*! Maximum message size used to avoid fragmentation, set ONLY in LARGE_DATA. If this value is
-     * not zero, the network factory will allow the initialization of UDP transports with maxMessageSize
+    /*!
+     * @brief Maximum message size used to avoid fragmentation, set ONLY in LARGE_DATA.
+     * If this value is not zero, the network factory will allow the initialization of UDP transports with maxMessageSize
      * higher than 65500K.
      */
     uint32_t max_msg_size_no_frag;

include/fastdds/dds/domain/DomainParticipant.hpp

@@ -673,6 +673,7 @@ class DomainParticipant : public Entity
      *
      * @param[out] participant_handles Reference to the vector where discovered participants will be returned
      * @return RETCODE_OK if everything correct, error code otherwise
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_discovered_participants(
@@ -684,6 +685,7 @@ class DomainParticipant : public Entity
      * @param[out] participant_data Reference to the ParticipantBuiltinTopicData object to return the data
      * @param participant_handle InstanceHandle of DomainParticipant to retrieve the data from
      * @return RETCODE_OK if everything correct, PRECONDITION_NOT_MET if participant does not exist
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_discovered_participant_data(
@@ -695,6 +697,7 @@ class DomainParticipant : public Entity
      *
      * @param[out] topic_handles Reference to the vector where discovered topics will be returned
      * @return RETCODE_OK if everything correct, error code otherwise
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_discovered_topics(

include/fastdds/dds/domain/DomainParticipantFactory.hpp

@@ -139,7 +139,7 @@ class DomainParticipantFactory
      * Returns all participants that belongs to the specified domain_id.
      *
      * @param domain_id
-     * @return previously created DomainParticipants within the specified domain
+     * @return previously created DomainParticipant instances within the specified domain
      */
     RTPS_DllAPI std::vector<DomainParticipant*> lookup_participants(
             DomainId_t domain_id) const;

include/fastdds/dds/domain/DomainParticipantListener.hpp

@@ -187,9 +187,7 @@ class DomainParticipantListener :
     /*!
      * This method is called when a participant discovers a new Type
      * The ownership of all object belongs to the caller so if needs to be used after the
-     * method ends, a full copy should be perform (except for dyn_type due to its shared_ptr nature.
-     * For example:
-     * fastrtps::types::TypeIdentifier new_type_id = \*identifier;
+     * method ends, a full copy should be performed (except for dyn_type due to its shared_ptr nature).
      */
     virtual void on_type_discovery(
             DomainParticipant* participant,

include/fastdds/dds/publisher/DataWriter.hpp

@@ -514,6 +514,7 @@ class DataWriter : public DomainEntity
      * @param[out] subscription_data subscription data struct
      * @param subscription_handle InstanceHandle_t of the subscription
      * @return RETCODE_OK
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_matched_subscription_data(
@@ -525,6 +526,7 @@ class DataWriter : public DomainEntity
      *
      * @param[out] subscription_handles Vector where the InstanceHandle_t are returned
      * @return RETCODE_OK
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_matched_subscriptions(

include/fastdds/dds/publisher/Publisher.hpp

@@ -217,6 +217,7 @@ class Publisher : public DomainEntity
      * @brief Indicates to FastDDS that the contained DataWriters are about to be modified
      *
      * @return RETCODE_OK if successful, an error code otherwise
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t suspend_publications();
@@ -225,6 +226,7 @@ class Publisher : public DomainEntity
      * @brief Indicates to FastDDS that the modifications to the DataWriters are complete.
      *
      * @return RETCODE_OK if successful, an error code otherwise
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t resume_publications();
@@ -233,6 +235,7 @@ class Publisher : public DomainEntity
      * @brief Signals the beginning of a set of coherent cache changes using the Datawriters attached to the publisher
      *
      * @return RETCODE_OK if successful, an error code otherwise
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t begin_coherent_changes();
@@ -241,6 +244,7 @@ class Publisher : public DomainEntity
      * @brief Signals the end of a set of coherent cache changes
      *
      * @return RETCODE_OK if successful, an error code otherwise
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t end_coherent_changes();
@@ -322,6 +326,8 @@ class Publisher : public DomainEntity
      * @param[out] writer_qos
      * @param[in] topic_qos
      * @return RETCODE_OK if successful, an error code otherwise
+     *
+     * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI static ReturnCode_t copy_from_topic_qos(
             fastdds::dds::DataWriterQos& writer_qos,

include/fastdds/dds/subscriber/DataReader.hpp

@@ -136,6 +136,7 @@ class DataReader : public DomainEntity
      *
      * @param[in] max_wait Max blocking time for this operation.
      * @return RETCODE_OK if there is new unread message, ReturnCode_t::RETCODE_TIMEOUT if timeout
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t wait_for_historical_data(
@@ -764,6 +765,7 @@ class DataReader : public DomainEntity
      * @param[in] handle
      *
      * @return Any of the standard return codes.
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_key_value(
@@ -976,6 +978,7 @@ class DataReader : public DomainEntity
      * @param[out] publication_data publication data struct
      * @param publication_handle InstanceHandle_t of the publication
      * @return RETCODE_OK
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_matched_publication_data(
@@ -987,6 +990,7 @@ class DataReader : public DomainEntity
      *
      * @param[out] publication_handles Vector where the InstanceHandle_t are returned
      * @return RETCODE_OK
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_matched_publications(

include/fastdds/dds/subscriber/Subscriber.hpp

@@ -234,6 +234,7 @@ class Subscriber : public DomainEntity
      * @param view_states Vector of ViewStateKind
      * @param instance_states Vector of InstanceStateKind
      * @return RETCODE_OK
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t get_datareaders(
@@ -254,6 +255,7 @@ class Subscriber : public DomainEntity
      * attached to the Subscriber.
      *
      * @return RETCODE_OK
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t begin_access();
@@ -263,6 +265,7 @@ class Subscriber : public DomainEntity
      * the Subscriber.
      *
      * @return RETCODE_OK
+     *
      * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI ReturnCode_t end_access();
@@ -360,6 +363,8 @@ class Subscriber : public DomainEntity
      * @param[in, out] reader_qos
      * @param[in] topic_qos
      * @return RETCODE_OK if successful, an error code otherwise
+     *
+     * @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
      */
     RTPS_DllAPI static ReturnCode_t copy_from_topic_qos(
             DataReaderQos& reader_qos,

include/fastdds/rtps/common/ChangeKind_t.hpp

@@ -26,8 +26,7 @@ namespace fastrtps {
 namespace rtps {
 
 /**
- * @enum ChangeKind_t, different types of CacheChange_t.
- * @ingroup COMMON_MODULE
+ * Enumerates the different types of CacheChange_t.
  */
 enum RTPS_DllAPI ChangeKind_t
 {

include/fastdds/rtps/common/FragmentNumber.h

@@ -19,37 +19,38 @@
 #ifndef _FASTDDS_RTPS_RPTS_ELEM_FRAGNUM_H_
 #define _FASTDDS_RTPS_RPTS_ELEM_FRAGNUM_H_
 
+#include <algorithm>
+#include <cmath>
+#include <set>
+
+#include <fastdds/rtps/common/Types.h>
 #include <fastrtps/fastrtps_dll.h>
 #include <fastrtps/utils/fixed_size_bitmap.hpp>
-#include <fastdds/rtps/common/Types.h>
 
-#include <set>
-#include <cmath>
-#include <algorithm>
-
-namespace eprosima{
-namespace fastrtps{
-namespace rtps{
+namespace eprosima {
+namespace fastrtps {
+namespace rtps {
 
 using FragmentNumber_t = uint32_t;
 
 //!Structure FragmentNumberSet_t, contains a group of fragmentnumbers.
-//!@ingroup COMMON_MODULE
 using FragmentNumberSet_t = BitmapRange<FragmentNumber_t>;
 
-inline std::ostream& operator<<(std::ostream& output, const FragmentNumberSet_t& fns)
+inline std::ostream& operator <<(
+        std::ostream& output,
+        const FragmentNumberSet_t& fns)
 {
     output << fns.base() << ":";
     fns.for_each([&](FragmentNumber_t it)
-    {
-        output << it << "-";
-    });
+            {
+                output << it << "-";
+            });
 
     return output;
 }
 
-}
-}
-}
+} // namespace rtps
+} // namespace fastrtps
+} // namespace eprosima
 
 #endif /* _FASTDDS_RTPS_RPTS_ELEM_FRAGNUM_H_ */

include/fastdds/rtps/common/MatchingInfo.h

@@ -22,22 +22,23 @@
 
 #include <fastdds/rtps/common/Guid.h>
 
-namespace eprosima{
-namespace fastrtps{
-namespace rtps{
+namespace eprosima {
+namespace fastrtps {
+namespace rtps {
 
 /**
- * @enum MatchingStatus, indicates whether the matched publication/subscription method of the PublisherListener or SubscriberListener has
+ * Indicates whether the matched publication/subscription method of the PublisherListener or SubscriberListener has
  * been called for a matching or a removal of a remote endpoint.
- * @ingroup COMMON_MODULE
  */
 #if defined(_WIN32)
-    enum RTPS_DllAPI MatchingStatus{
+enum RTPS_DllAPI MatchingStatus
+{
 #else
-        enum MatchingStatus{
-#endif
-    MATCHED_MATCHING,//!< MATCHED_MATCHING, new publisher/subscriber found
-    REMOVED_MATCHING //!< REMOVED_MATCHING, publisher/subscriber removed
+enum MatchingStatus
+{
+#endif  // if defined(_WIN32)
+    MATCHED_MATCHING,  //!< MATCHED_MATCHING, new publisher/subscriber found
+    REMOVED_MATCHING   //!< REMOVED_MATCHING, publisher/subscriber removed
 
 };
 
@@ -48,21 +49,36 @@ namespace rtps{
 class RTPS_DllAPI MatchingInfo
 {
 public:
-    //!Default constructor
-    MatchingInfo():status(MATCHED_MATCHING){};
+
+    //! Default constructor
+    MatchingInfo()
+        : status(MATCHED_MATCHING)
+    {
+    }
+
     /**
-    * @param stat Status
-    * @param guid GUID
-    */
-    MatchingInfo(MatchingStatus stat,const GUID_t&guid):status(stat),remoteEndpointGuid(guid){};
-    ~MatchingInfo(){};
-    //!Status
+     * @param stat Status
+     * @param guid GUID
+     */
+    MatchingInfo(
+            MatchingStatus stat,
+            const GUID_t& guid)
+        : status(stat)
+        , remoteEndpointGuid(guid)
+    {
+    }
+
+    ~MatchingInfo()
+    {
+    }
+
+    //! Status
     MatchingStatus status;
-    //!Remote endpoint GUID
+    //! Remote endpoint GUID
     GUID_t remoteEndpointGuid;
 };
-}
-}
-}
+} // namespace rtps
+} // namespace fastrtps
+} // namespace eprosima
 
 #endif /* _FASTDDS_RTPS_MATCHINGINFO_H_ */

include/fastdds/rtps/common/SequenceNumber.h

@@ -32,7 +32,6 @@ namespace eprosima {
 namespace fastrtps {
 namespace rtps {
 
-
 //!@brief Structure SequenceNumber_t, different for each change in the same writer.
 //!@ingroup COMMON_MODULE
 struct RTPS_DllAPI SequenceNumber_t
@@ -42,7 +41,7 @@ struct RTPS_DllAPI SequenceNumber_t
     //!
     uint32_t low = 0;
 
-    //!Default constructor
+    //! Default constructor
     SequenceNumber_t() noexcept
     {
         high = 0;
@@ -366,8 +365,7 @@ struct SequenceNumberDiff
 
 #endif // ifndef DOXYGEN_SHOULD_SKIP_THIS_PUBLIC
 
-//!Structure SequenceNumberSet_t, contains a group of sequencenumbers.
-//!@ingroup COMMON_MODULE
+//! Structure SequenceNumberSet_t, contains a group of sequencenumbers.
 using SequenceNumberSet_t = BitmapRange<SequenceNumber_t, SequenceNumberDiff, 256>;
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS_PUBLIC