Adjust doxygen so Fast DDS Python pydoc makes RTD build (#5026)

EduPonz · web-flow · commit a78316bc4650 · 2024-07-03T11:08:17.000+02:00
* Refs #21114: Fix dispose Signed-off-by: eduponz <eduardoponz@eprosima.com> Refs #21114: Split return into several @return Signed-off-by: eduponz <eduardoponz@eprosima.com> * Refs #21114: Fix register_instance Signed-off-by: eduponz <eduardoponz@eprosima.com> * Refs #21114: Fix unregister_instance Signed-off-by: eduponz <eduardoponz@eprosima.com> * Refs #21114: Fix read_next_instance_w_condition Signed-off-by: eduponz <eduardoponz@eprosima.com> * Refs #21114: Fix take_w_condition Signed-off-by: eduponz <eduardoponz@eprosima.com> * Refs #21114: Fix take_instance Signed-off-by: eduponz <eduardoponz@eprosima.com> * Refs #21114: Fix take_next_instance Signed-off-by: eduponz <eduardoponz@eprosima.com> * Refs #21114: Fix take_next_instance_w_condition Signed-off-by: eduponz <eduardoponz@eprosima.com> --------- Signed-off-by: eduponz <eduardoponz@eprosima.com>
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,
diff --git a/include/fastdds/dds/subscriber/DataReader.hpp b/include/fastdds/dds/subscriber/DataReader.hpp
@@ -455,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
@@ -464,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.
      */
@@ -562,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.
      */
@@ -590,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.
      */
@@ -630,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.
      */
@@ -669,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.
      */
