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

* Remove doxygen warnings (#4700, #5011) (#5016) * Refs #21114: Remove doxygen warnings Signed-off-by: eduponz <[email protected]> * Refs #21114: Apply Miguel's suggestions Signed-off-by: eduponz <[email protected]> --------- Signed-off-by: eduponz <[email protected]> (cherry picked from commit 28a2e15) # Conflicts: # include/fastdds/dds/core/policy/QosPolicies.hpp # include/fastdds/dds/publisher/Publisher.hpp # include/fastdds/dds/subscriber/Subscriber.hpp Signed-off-by: JesusPoderoso <[email protected]> * Adjust doxygen so Fast DDS Python pydoc makes RTD build (#5026) * Refs #21114: Fix dispose Signed-off-by: eduponz <[email protected]> Refs #21114: Split return into several @return Signed-off-by: eduponz <[email protected]> * Refs #21114: Fix register_instance Signed-off-by: eduponz <[email protected]> * Refs #21114: Fix unregister_instance Signed-off-by: eduponz <[email protected]> * Refs #21114: Fix read_next_instance_w_condition Signed-off-by: eduponz <[email protected]> * Refs #21114: Fix take_w_condition Signed-off-by: eduponz <[email protected]> * Refs #21114: Fix take_instance Signed-off-by: eduponz <[email protected]> * Refs #21114: Fix take_next_instance Signed-off-by: eduponz <[email protected]> * Refs #21114: Fix take_next_instance_w_condition Signed-off-by: eduponz <[email protected]> --------- Signed-off-by: eduponz <[email protected]> Signed-off-by: JesusPoderoso <[email protected]> --------- Signed-off-by: eduponz <[email protected]> Signed-off-by: JesusPoderoso <[email protected]> Co-authored-by: Eduardo Ponz Segrelles <[email protected]>
eProsima · Jul 3, 2024 · a886cff · a886cff
1 parent a0a4fee
commit a886cff
Show file tree

Hide file tree

Showing 12 changed files with 144 additions and 117 deletions.
diff --git a/include/fastdds/dds/domain/DomainParticipant.hpp b/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(

diff --git a/include/fastdds/dds/domain/DomainParticipantFactory.hpp b/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;

diff --git a/include/fastdds/dds/domain/DomainParticipantListener.hpp b/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,

diff --git a/include/fastdds/dds/publisher/DataWriter.hpp b/include/fastdds/dds/publisher/DataWriter.hpp
@@ -198,12 +198,14 @@ class DataWriter : public DomainEntity
 
     /*!
      * @brief Informs that the application will be modifying a particular instance.
+     *
      * It gives an opportunity to the middleware to pre-configure itself to improve performance.
+     * The returned handle could be used in successive `write` or `dispose` operations.
      *
      * @param[in] instance Sample used to get the instance's key.
+     *
      * @return Handle containing the instance's key.
-     * This handle could be used in successive `write` or `dispose` operations.
-     * In case of error, HANDLE_NIL will be returned.
+     * @return HANDLE_NIL in case of error.
      */
     RTPS_DllAPI InstanceHandle_t register_instance(
             void* instance);
@@ -246,8 +248,8 @@ class DataWriter : public DomainEntity
      *
      * @param[in] instance Sample used to deduce instance's key in case of `handle` parameter is HANDLE_NIL.
      * @param[in] handle Instance's key to be unregistered.
-     * @return Returns the operation's result.
-     * If the operation finishes successfully, ReturnCode_t::RETCODE_OK is returned.
+     *
+     * @return ReturnCode_t
      */
     RTPS_DllAPI ReturnCode_t unregister_instance(
             void* instance,
@@ -447,8 +449,10 @@ class DataWriter : public DomainEntity
      *
      * @param[in] data Sample used to deduce instance's key in case of `handle` parameter is HANDLE_NIL.
      * @param[in] handle InstanceHandle of the data
-     * @return RETCODE_PRECONDITION_NOT_MET if the handle introduced does not match with the one associated to the data,
-     * RETCODE_OK if the data is correctly sent and RETCODE_ERROR otherwise.
+     *
+     * @return RETCODE_PRECONDITION_NOT_MET if the handle introduced does not match with the one associated to the data.
+     * @return RETCODE_OK if the data is correctly sent.
+     * @return RETCODE_ERROR otherwise.
      */
     RTPS_DllAPI ReturnCode_t dispose(
             void* data,
@@ -514,6 +518,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 +530,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(

diff --git a/include/fastdds/dds/publisher/Publisher.hpp b/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,7 @@ 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 ReturnCode_t copy_from_topic_qos(

diff --git a/include/fastdds/dds/subscriber/DataReader.hpp b/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(
@@ -454,7 +455,7 @@ class DataReader : public DomainEntity
      * This operation accesses a collection of Data values from the DataReader. The behavior is identical to
      * @ref read_next_instance except that all samples returned satisfy the specified condition. In other words, on
      * success all returned samples belong to the same instance, and the instance is the instance with
-     * ‘smallest’ @c instance_handle among the ones that verify (a) @c instance_handle >= @c previous_handle and (b) have samples
+     * 'smallest' @c instance_handle among the ones that verify (a) @c instance_handle >= @c previous_handle and (b) have samples
      * for which the specified ReadCondition evaluates to TRUE.
      *
      * Similar to the operation @ref read_next_instance it is possible to call
@@ -463,19 +464,19 @@ class DataReader : public DomainEntity
      *
      * The behavior of the @ref read_next_instance_w_condition operation follows the same rules than the read operation
      * regarding the pre-conditions and post-conditions for the @c data_values and @c sample_infos collections. Similar
-     * to read, the @ref read_next_instance_w_condition operation may ‘loan’ elements to the output collections which
+     * to read, the @ref read_next_instance_w_condition operation may 'loan' elements to the output collections which
      * must then be returned by means of @ref return_loan.
      *
      * If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA.
      *
-     * @param[in,out] data_values     A LoanableCollection object where the received data samples will be returned.
-     * @param[in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
-     * @param[in]     max_samples     The maximum number of samples to be returned. If the special value
-     *                                @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
-     *                                available, up to the limits described in the documentation for @ref read().
-     * @param[in]     previous_handle The 'next smallest' instance with a value greater than this value that has
-     *                                available samples will be returned.
-     * @param[in]     a_condition     A ReadCondition that returned @c data_values must pass
+     * @param [in,out] data_values     A LoanableCollection object where the received data samples will be returned.
+     * @param [in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
+     * @param [in]     max_samples     The maximum number of samples to be returned. If the special value
+     *                                 @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
+     *                                 available, up to the limits described in the documentation for @ref read().
+     * @param [in]     previous_handle The 'next smallest' instance with a value greater than this value that has
+     *                                 available samples will be returned.
+     * @param [in]     a_condition     A ReadCondition that returned @c data_values must pass
      *
      * @return Any of the standard return codes.
      */
@@ -561,11 +562,11 @@ class DataReader : public DomainEntity
      *
      * If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA.
      *
-     * @param[in,out] data_values     A LoanableCollection object where the received data samples will be returned.
-     * @param[in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
-     * @param[in]     max_samples     The maximum number of samples to be returned. If the special value
-     *                                @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are.
-     * @param[in]     a_condition     A ReadCondition that returned @c data_values must pass
+     * @param [in,out] data_values     A LoanableCollection object where the received data samples will be returned.
+     * @param [in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
+     * @param [in]     max_samples     The maximum number of samples to be returned. If the special value
+     *                                 @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are.
+     * @param [in]     a_condition     A ReadCondition that returned @c data_values must pass
      *
      * @return Any of the standard return codes.
      */
@@ -589,17 +590,17 @@ class DataReader : public DomainEntity
      *
      * If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.
      *
-     * @param[in,out] data_values     A LoanableCollection object where the received data samples will be returned.
-     * @param[in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
-     * @param[in]     max_samples     The maximum number of samples to be returned. If the special value
-     *                                @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
-     *                                available, up to the limits described in the documentation for @ref read().
-     * @param[in]     a_handle        The specified instance to return samples for. The method will fail with
-     *                                RETCODE_BAD_PARAMETER if the handle does not correspond to an existing
-     *                                data-object known to the DataReader.
-     * @param[in]     sample_states   Only data samples with @c sample_state matching one of these will be returned.
-     * @param[in]     view_states     Only data samples with @c view_state matching one of these will be returned.
-     * @param[in]     instance_states Only data samples with @c instance_state matching one of these will be returned.
+     * @param [in,out] data_values     A LoanableCollection object where the received data samples will be returned.
+     * @param [in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
+     * @param [in]     max_samples     The maximum number of samples to be returned. If the special value
+     *                                 @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
+     *                                 available, up to the limits described in the documentation for @ref read().
+     * @param [in]     a_handle        The specified instance to return samples for. The method will fail with
+     *                                 RETCODE_BAD_PARAMETER if the handle does not correspond to an existing
+     *                                 data-object known to the DataReader.
+     * @param [in]     sample_states   Only data samples with @c sample_state matching one of these will be returned.
+     * @param [in]     view_states     Only data samples with @c view_state matching one of these will be returned.
+     * @param [in]     instance_states Only data samples with @c instance_state matching one of these will be returned.
      *
      * @return Any of the standard return codes.
      */
@@ -629,16 +630,16 @@ class DataReader : public DomainEntity
      *
      * If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.
      *
-     * @param[in,out] data_values     A LoanableCollection object where the received data samples will be returned.
-     * @param[in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
-     * @param[in]     max_samples     The maximum number of samples to be returned. If the special value
-     *                                @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
-     *                                available, up to the limits described in the documentation for @ref read().
-     * @param[in]     previous_handle The 'next smallest' instance with a value greater than this value that has
-     *                                available samples will be returned.
-     * @param[in]     sample_states   Only data samples with @c sample_state matching one of these will be returned.
-     * @param[in]     view_states     Only data samples with @c view_state matching one of these will be returned.
-     * @param[in]     instance_states Only data samples with @c instance_state matching one of these will be returned.
+     * @param [in,out] data_values     A LoanableCollection object where the received data samples will be returned.
+     * @param [in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
+     * @param [in]     max_samples     The maximum number of samples to be returned. If the special value
+     *                                 @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
+     *                                 available, up to the limits described in the documentation for @ref read().
+     * @param [in]     previous_handle The 'next smallest' instance with a value greater than this value that has
+     *                                 available samples will be returned.
+     * @param [in]     sample_states   Only data samples with @c sample_state matching one of these will be returned.
+     * @param [in]     view_states     Only data samples with @c view_state matching one of these will be returned.
+     * @param [in]     instance_states Only data samples with @c instance_state matching one of these will be returned.
      *
      * @return Any of the standard return codes.
      */
@@ -668,14 +669,14 @@ class DataReader : public DomainEntity
      *
      * If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA
      *
-     * @param[in,out] data_values     A LoanableCollection object where the received data samples will be returned.
-     * @param[in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
-     * @param[in]     max_samples     The maximum number of samples to be returned. If the special value
-     *                                @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
-     *                                available, up to the limits described in the documentation for @ref read().
-     * @param[in]     previous_handle The 'next smallest' instance with a value greater than this value that has
-     *                                available samples will be returned.
-     * @param[in]     a_condition     A ReadCondition that returned @c data_values must pass
+     * @param [in,out] data_values     A LoanableCollection object where the received data samples will be returned.
+     * @param [in,out] sample_infos    A SampleInfoSeq object where the received sample info will be returned.
+     * @param [in]     max_samples     The maximum number of samples to be returned. If the special value
+     *                                 @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
+     *                                 available, up to the limits described in the documentation for @ref read().
+     * @param [in]     previous_handle The 'next smallest' instance with a value greater than this value that has
+     *                                 available samples will be returned.
+     * @param [in]     a_condition     A ReadCondition that returned @c data_values must pass
      *
      * @return Any of the standard return codes.
      */
@@ -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(