Skip to content

Commit 0e4e234

Browse files
mergify[bot]EduPonz
mergify[bot]
and
EduPonz
authored
Remove doxygen warnings (#4700, #5011) (#5016) (#5025)
* 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> (cherry picked from commit 28a2e15) Signed-off-by: eduponz <eduardoponz@eprosima.com> * Adjust doxygen so Fast DDS Python pydoc makes RTD build (#5026) * 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> --------- Signed-off-by: eduponz <eduardoponz@eprosima.com> Co-authored-by: Eduardo Ponz Segrelles <eduardoponz@eprosima.com>
1 parent 5ad987a commit 0e4e234

12 files changed

Lines changed: 144 additions & 117 deletions

‎include/fastdds/dds/domain/DomainParticipant.hpp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -673,6 +673,7 @@ class DomainParticipant : public Entity
673673
*
674674
* @param[out] participant_handles Reference to the vector where discovered participants will be returned
675675
* @return RETCODE_OK if everything correct, error code otherwise
676+
*
676677
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
677678
*/
678679
RTPS_DllAPI ReturnCode_t get_discovered_participants(
@@ -684,6 +685,7 @@ class DomainParticipant : public Entity
684685
* @param[out] participant_data Reference to the ParticipantBuiltinTopicData object to return the data
685686
* @param participant_handle InstanceHandle of DomainParticipant to retrieve the data from
686687
* @return RETCODE_OK if everything correct, PRECONDITION_NOT_MET if participant does not exist
688+
*
687689
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
688690
*/
689691
RTPS_DllAPI ReturnCode_t get_discovered_participant_data(
@@ -695,6 +697,7 @@ class DomainParticipant : public Entity
695697
*
696698
* @param[out] topic_handles Reference to the vector where discovered topics will be returned
697699
* @return RETCODE_OK if everything correct, error code otherwise
700+
*
698701
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
699702
*/
700703
RTPS_DllAPI ReturnCode_t get_discovered_topics(

‎include/fastdds/dds/domain/DomainParticipantFactory.hpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ class DomainParticipantFactory
139139
* Returns all participants that belongs to the specified domain_id.
140140
*
141141
* @param domain_id
142-
* @return previously created DomainParticipants within the specified domain
142+
* @return previously created DomainParticipant instances within the specified domain
143143
*/
144144
RTPS_DllAPI std::vector<DomainParticipant*> lookup_participants(
145145
DomainId_t domain_id) const;

‎include/fastdds/dds/domain/DomainParticipantListener.hpp‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -186,9 +186,7 @@ class DomainParticipantListener :
186186
/*!
187187
* This method is called when a participant discovers a new Type
188188
* The ownership of all object belongs to the caller so if needs to be used after the
189-
* method ends, a full copy should be perform (except for dyn_type due to its shared_ptr nature.
190-
* For example:
191-
* fastrtps::types::TypeIdentifier new_type_id = \*identifier;
189+
* method ends, a full copy should be performed (except for dyn_type due to its shared_ptr nature).
192190
*/
193191
virtual void on_type_discovery(
194192
DomainParticipant* participant,

‎include/fastdds/dds/publisher/DataWriter.hpp‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -198,12 +198,14 @@ class DataWriter : public DomainEntity
198198

199199
/*!
200200
* @brief Informs that the application will be modifying a particular instance.
201+
*
201202
* It gives an opportunity to the middleware to pre-configure itself to improve performance.
203+
* The returned handle could be used in successive `write` or `dispose` operations.
202204
*
203205
* @param[in] instance Sample used to get the instance's key.
206+
*
204207
* @return Handle containing the instance's key.
205-
* This handle could be used in successive `write` or `dispose` operations.
206-
* In case of error, HANDLE_NIL will be returned.
208+
* @return HANDLE_NIL in case of error.
207209
*/
208210
RTPS_DllAPI InstanceHandle_t register_instance(
209211
void* instance);
@@ -246,8 +248,8 @@ class DataWriter : public DomainEntity
246248
*
247249
* @param[in] instance Sample used to deduce instance's key in case of `handle` parameter is HANDLE_NIL.
248250
* @param[in] handle Instance's key to be unregistered.
249-
* @return Returns the operation's result.
250-
* If the operation finishes successfully, ReturnCode_t::RETCODE_OK is returned.
251+
*
252+
* @return ReturnCode_t
251253
*/
252254
RTPS_DllAPI ReturnCode_t unregister_instance(
253255
void* instance,
@@ -447,8 +449,10 @@ class DataWriter : public DomainEntity
447449
*
448450
* @param[in] data Sample used to deduce instance's key in case of `handle` parameter is HANDLE_NIL.
449451
* @param[in] handle InstanceHandle of the data
450-
* @return RETCODE_PRECONDITION_NOT_MET if the handle introduced does not match with the one associated to the data,
451-
* RETCODE_OK if the data is correctly sent and RETCODE_ERROR otherwise.
452+
*
453+
* @return RETCODE_PRECONDITION_NOT_MET if the handle introduced does not match with the one associated to the data.
454+
* @return RETCODE_OK if the data is correctly sent.
455+
* @return RETCODE_ERROR otherwise.
452456
*/
453457
RTPS_DllAPI ReturnCode_t dispose(
454458
void* data,
@@ -514,6 +518,7 @@ class DataWriter : public DomainEntity
514518
* @param[out] subscription_data subscription data struct
515519
* @param subscription_handle InstanceHandle_t of the subscription
516520
* @return RETCODE_OK
521+
*
517522
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
518523
*/
519524
RTPS_DllAPI ReturnCode_t get_matched_subscription_data(
@@ -525,6 +530,7 @@ class DataWriter : public DomainEntity
525530
*
526531
* @param[out] subscription_handles Vector where the InstanceHandle_t are returned
527532
* @return RETCODE_OK
533+
*
528534
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
529535
*/
530536
RTPS_DllAPI ReturnCode_t get_matched_subscriptions(

‎include/fastdds/dds/publisher/Publisher.hpp‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,7 @@ class Publisher : public DomainEntity
247247
* @brief Indicates to FastDDS that the contained DataWriters are about to be modified
248248
*
249249
* @return RETCODE_OK if successful, an error code otherwise
250+
*
250251
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
251252
*/
252253
RTPS_DllAPI ReturnCode_t suspend_publications();
@@ -255,6 +256,7 @@ class Publisher : public DomainEntity
255256
* @brief Indicates to FastDDS that the modifications to the DataWriters are complete.
256257
*
257258
* @return RETCODE_OK if successful, an error code otherwise
259+
*
258260
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
259261
*/
260262
RTPS_DllAPI ReturnCode_t resume_publications();
@@ -263,6 +265,7 @@ class Publisher : public DomainEntity
263265
* @brief Signals the beginning of a set of coherent cache changes using the Datawriters attached to the publisher
264266
*
265267
* @return RETCODE_OK if successful, an error code otherwise
268+
*
266269
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
267270
*/
268271
RTPS_DllAPI ReturnCode_t begin_coherent_changes();
@@ -271,6 +274,7 @@ class Publisher : public DomainEntity
271274
* @brief Signals the end of a set of coherent cache changes
272275
*
273276
* @return RETCODE_OK if successful, an error code otherwise
277+
*
274278
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
275279
*/
276280
RTPS_DllAPI ReturnCode_t end_coherent_changes();
@@ -352,6 +356,7 @@ class Publisher : public DomainEntity
352356
* @param[out] writer_qos
353357
* @param[in] topic_qos
354358
* @return RETCODE_OK if successful, an error code otherwise
359+
*
355360
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
356361
*/
357362
RTPS_DllAPI ReturnCode_t copy_from_topic_qos(

‎include/fastdds/dds/subscriber/DataReader.hpp‎

Lines changed: 48 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ class DataReader : public DomainEntity
136136
*
137137
* @param[in] max_wait Max blocking time for this operation.
138138
* @return RETCODE_OK if there is new unread message, ReturnCode_t::RETCODE_TIMEOUT if timeout
139+
*
139140
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
140141
*/
141142
RTPS_DllAPI ReturnCode_t wait_for_historical_data(
@@ -454,7 +455,7 @@ class DataReader : public DomainEntity
454455
* This operation accesses a collection of Data values from the DataReader. The behavior is identical to
455456
* @ref read_next_instance except that all samples returned satisfy the specified condition. In other words, on
456457
* success all returned samples belong to the same instance, and the instance is the instance with
457-
* ‘smallest’ @c instance_handle among the ones that verify (a) @c instance_handle >= @c previous_handle and (b) have samples
458+
* 'smallest' @c instance_handle among the ones that verify (a) @c instance_handle >= @c previous_handle and (b) have samples
458459
* for which the specified ReadCondition evaluates to TRUE.
459460
*
460461
* Similar to the operation @ref read_next_instance it is possible to call
@@ -463,19 +464,19 @@ class DataReader : public DomainEntity
463464
*
464465
* The behavior of the @ref read_next_instance_w_condition operation follows the same rules than the read operation
465466
* regarding the pre-conditions and post-conditions for the @c data_values and @c sample_infos collections. Similar
466-
* to read, the @ref read_next_instance_w_condition operation may ‘loan’ elements to the output collections which
467+
* to read, the @ref read_next_instance_w_condition operation may 'loan' elements to the output collections which
467468
* must then be returned by means of @ref return_loan.
468469
*
469470
* If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA.
470471
*
471-
* @param[in,out] data_values A LoanableCollection object where the received data samples will be returned.
472-
* @param[in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
473-
* @param[in] max_samples The maximum number of samples to be returned. If the special value
474-
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
475-
* available, up to the limits described in the documentation for @ref read().
476-
* @param[in] previous_handle The 'next smallest' instance with a value greater than this value that has
477-
* available samples will be returned.
478-
* @param[in] a_condition A ReadCondition that returned @c data_values must pass
472+
* @param [in,out] data_values A LoanableCollection object where the received data samples will be returned.
473+
* @param [in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
474+
* @param [in] max_samples The maximum number of samples to be returned. If the special value
475+
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
476+
* available, up to the limits described in the documentation for @ref read().
477+
* @param [in] previous_handle The 'next smallest' instance with a value greater than this value that has
478+
* available samples will be returned.
479+
* @param [in] a_condition A ReadCondition that returned @c data_values must pass
479480
*
480481
* @return Any of the standard return codes.
481482
*/
@@ -561,11 +562,11 @@ class DataReader : public DomainEntity
561562
*
562563
* If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA.
563564
*
564-
* @param[in,out] data_values A LoanableCollection object where the received data samples will be returned.
565-
* @param[in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
566-
* @param[in] max_samples The maximum number of samples to be returned. If the special value
567-
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are.
568-
* @param[in] a_condition A ReadCondition that returned @c data_values must pass
565+
* @param [in,out] data_values A LoanableCollection object where the received data samples will be returned.
566+
* @param [in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
567+
* @param [in] max_samples The maximum number of samples to be returned. If the special value
568+
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are.
569+
* @param [in] a_condition A ReadCondition that returned @c data_values must pass
569570
*
570571
* @return Any of the standard return codes.
571572
*/
@@ -589,17 +590,17 @@ class DataReader : public DomainEntity
589590
*
590591
* If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.
591592
*
592-
* @param[in,out] data_values A LoanableCollection object where the received data samples will be returned.
593-
* @param[in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
594-
* @param[in] max_samples The maximum number of samples to be returned. If the special value
595-
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
596-
* available, up to the limits described in the documentation for @ref read().
597-
* @param[in] a_handle The specified instance to return samples for. The method will fail with
598-
* RETCODE_BAD_PARAMETER if the handle does not correspond to an existing
599-
* data-object known to the DataReader.
600-
* @param[in] sample_states Only data samples with @c sample_state matching one of these will be returned.
601-
* @param[in] view_states Only data samples with @c view_state matching one of these will be returned.
602-
* @param[in] instance_states Only data samples with @c instance_state matching one of these will be returned.
593+
* @param [in,out] data_values A LoanableCollection object where the received data samples will be returned.
594+
* @param [in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
595+
* @param [in] max_samples The maximum number of samples to be returned. If the special value
596+
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
597+
* available, up to the limits described in the documentation for @ref read().
598+
* @param [in] a_handle The specified instance to return samples for. The method will fail with
599+
* RETCODE_BAD_PARAMETER if the handle does not correspond to an existing
600+
* data-object known to the DataReader.
601+
* @param [in] sample_states Only data samples with @c sample_state matching one of these will be returned.
602+
* @param [in] view_states Only data samples with @c view_state matching one of these will be returned.
603+
* @param [in] instance_states Only data samples with @c instance_state matching one of these will be returned.
603604
*
604605
* @return Any of the standard return codes.
605606
*/
@@ -629,16 +630,16 @@ class DataReader : public DomainEntity
629630
*
630631
* If the DataReader has no samples that meet the constraints, the operations fails with RETCODE_NO_DATA.
631632
*
632-
* @param[in,out] data_values A LoanableCollection object where the received data samples will be returned.
633-
* @param[in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
634-
* @param[in] max_samples The maximum number of samples to be returned. If the special value
635-
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
636-
* available, up to the limits described in the documentation for @ref read().
637-
* @param[in] previous_handle The 'next smallest' instance with a value greater than this value that has
638-
* available samples will be returned.
639-
* @param[in] sample_states Only data samples with @c sample_state matching one of these will be returned.
640-
* @param[in] view_states Only data samples with @c view_state matching one of these will be returned.
641-
* @param[in] instance_states Only data samples with @c instance_state matching one of these will be returned.
633+
* @param [in,out] data_values A LoanableCollection object where the received data samples will be returned.
634+
* @param [in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
635+
* @param [in] max_samples The maximum number of samples to be returned. If the special value
636+
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
637+
* available, up to the limits described in the documentation for @ref read().
638+
* @param [in] previous_handle The 'next smallest' instance with a value greater than this value that has
639+
* available samples will be returned.
640+
* @param [in] sample_states Only data samples with @c sample_state matching one of these will be returned.
641+
* @param [in] view_states Only data samples with @c view_state matching one of these will be returned.
642+
* @param [in] instance_states Only data samples with @c instance_state matching one of these will be returned.
642643
*
643644
* @return Any of the standard return codes.
644645
*/
@@ -668,14 +669,14 @@ class DataReader : public DomainEntity
668669
*
669670
* If the DataReader has no samples that meet the constraints, the return value will be RETCODE_NO_DATA
670671
*
671-
* @param[in,out] data_values A LoanableCollection object where the received data samples will be returned.
672-
* @param[in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
673-
* @param[in] max_samples The maximum number of samples to be returned. If the special value
674-
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
675-
* available, up to the limits described in the documentation for @ref read().
676-
* @param[in] previous_handle The 'next smallest' instance with a value greater than this value that has
677-
* available samples will be returned.
678-
* @param[in] a_condition A ReadCondition that returned @c data_values must pass
672+
* @param [in,out] data_values A LoanableCollection object where the received data samples will be returned.
673+
* @param [in,out] sample_infos A SampleInfoSeq object where the received sample info will be returned.
674+
* @param [in] max_samples The maximum number of samples to be returned. If the special value
675+
* @ref LENGTH_UNLIMITED is provided, as many samples will be returned as are
676+
* available, up to the limits described in the documentation for @ref read().
677+
* @param [in] previous_handle The 'next smallest' instance with a value greater than this value that has
678+
* available samples will be returned.
679+
* @param [in] a_condition A ReadCondition that returned @c data_values must pass
679680
*
680681
* @return Any of the standard return codes.
681682
*/
@@ -764,6 +765,7 @@ class DataReader : public DomainEntity
764765
* @param[in] handle
765766
*
766767
* @return Any of the standard return codes.
768+
*
767769
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
768770
*/
769771
RTPS_DllAPI ReturnCode_t get_key_value(
@@ -976,6 +978,7 @@ class DataReader : public DomainEntity
976978
* @param[out] publication_data publication data struct
977979
* @param publication_handle InstanceHandle_t of the publication
978980
* @return RETCODE_OK
981+
*
979982
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
980983
*/
981984
RTPS_DllAPI ReturnCode_t get_matched_publication_data(
@@ -987,6 +990,7 @@ class DataReader : public DomainEntity
987990
*
988991
* @param[out] publication_handles Vector where the InstanceHandle_t are returned
989992
* @return RETCODE_OK
993+
*
990994
* @warning Not supported yet. Currently returns RETCODE_UNSUPPORTED
991995
*/
992996
RTPS_DllAPI ReturnCode_t get_matched_publications(

0 commit comments

Comments
 (0)