From 79b08300e9550a145aa91bcef07c1cfa3ba337e9 Mon Sep 17 00:00:00 2001 From: Thijs <33511165+ThijsSassen@users.noreply.github.com> Date: Wed, 29 Nov 2023 19:17:45 +0100 Subject: [PATCH] Documentation updates (#1888) * Fix for #1873 to generate proper rst links for attributes * Added missing API documentation * Update of hashes for generated config options files * Updated documentation on configuring shared memory to fix #1883 * Updated wrongly formatted refs and missing group refs in documentation headers * Made links better readable --- docs/manual/api/dynamic.rst | 6 ++ docs/manual/api/internal.rst | 11 +++ docs/manual/api/loan.rst | 6 ++ docs/manual/api/psmx.rst | 6 ++ docs/manual/config/config_file_reference.rst | 92 +++++++++---------- docs/manual/ddsc.rst | 2 + docs/manual/doxygen.conf.in | 2 +- docs/manual/options.md | 2 +- .../shared_memory/shared_mem_config.rst | 38 ++------ docs/manual/shared_memory/shared_memory.rst | 4 +- etc/cyclonedds.rnc | 2 +- etc/cyclonedds.xsd | 2 +- src/core/ddsc/include/dds/dds.h | 92 +++++++++---------- .../ddsc/include/dds/ddsc/dds_loaned_sample.h | 7 ++ src/core/ddsc/include/dds/ddsc/dds_psmx.h | 39 +++++++- .../dds/ddsc/dds_public_dynamic_type.h | 2 +- .../include/dds/ddsc/dds_public_loan_api.h | 14 +-- src/core/ddsi/defconfig.c | 2 +- src/tools/_confgen/generate_rst.c | 5 +- 19 files changed, 188 insertions(+), 146 deletions(-) create mode 100644 docs/manual/api/dynamic.rst create mode 100644 docs/manual/api/psmx.rst diff --git a/docs/manual/api/dynamic.rst b/docs/manual/api/dynamic.rst new file mode 100644 index 0000000000..6d03c363fa --- /dev/null +++ b/docs/manual/api/dynamic.rst @@ -0,0 +1,6 @@ +Dynamic Type API +================ + +.. doxygengroup:: dynamic_type + :project: ddsc_api_docs + :members: diff --git a/docs/manual/api/internal.rst b/docs/manual/api/internal.rst index 9a93ae14f7..8e9af1353b 100644 --- a/docs/manual/api/internal.rst +++ b/docs/manual/api/internal.rst @@ -7,15 +7,26 @@ All functionality in this section is considered internal. You should not build a :project: ddsc_api_docs :members: +Testing +------- .. doxygengroup:: testing :project: ddsc_api_docs :members: +Implementation +-------------- .. doxygengroup:: implementation :project: ddsc_api_docs :members: +Topic definition +---------------- .. doxygengroup:: topic_definition :project: ddsc_api_docs :members: +Convenience log category definitions +------------------------------------ +.. doxygengroup:: log_categories + :project: ddsc_api_docs + :members: diff --git a/docs/manual/api/loan.rst b/docs/manual/api/loan.rst index 13c0e2141f..91cf978f67 100644 --- a/docs/manual/api/loan.rst +++ b/docs/manual/api/loan.rst @@ -4,3 +4,9 @@ Loaning .. doxygengroup:: loan :project: ddsc_api_docs :members: + +Loaned Samples +-------------- +.. doxygengroup:: loaned_sample + :project: ddsc_api_docs + :members: \ No newline at end of file diff --git a/docs/manual/api/psmx.rst b/docs/manual/api/psmx.rst new file mode 100644 index 0000000000..f0c893aba1 --- /dev/null +++ b/docs/manual/api/psmx.rst @@ -0,0 +1,6 @@ +Publish Subscribe Message Exchange +================================== + +.. doxygengroup:: psmx + :project: ddsc_api_docs + :members: diff --git a/docs/manual/config/config_file_reference.rst b/docs/manual/config/config_file_reference.rst index 567c33032f..54f77f7faa 100644 --- a/docs/manual/config/config_file_reference.rst +++ b/docs/manual/config/config_file_reference.rst @@ -11,7 +11,7 @@ Below is the full (generated) reference of XML you can use to configure |var-pro //CycloneDDS ############ -Children: `//CycloneDDS/Domain`_ +Children: :ref:`Domain` CycloneDDS configuration @@ -21,8 +21,8 @@ CycloneDDS configuration //CycloneDDS/Domain ******************* -Attributes: [Id](`//CycloneDDS/Domain[@Id]`_) -Children: `//CycloneDDS/Domain/Compatibility`_, `//CycloneDDS/Domain/Discovery`_, `//CycloneDDS/Domain/General`_, `//CycloneDDS/Domain/Internal`_, `//CycloneDDS/Domain/Partitioning`_, `//CycloneDDS/Domain/SSL`_, `//CycloneDDS/Domain/Security`_, `//CycloneDDS/Domain/SharedMemory`_, `//CycloneDDS/Domain/Sizing`_, `//CycloneDDS/Domain/TCP`_, `//CycloneDDS/Domain/Threads`_, `//CycloneDDS/Domain/Tracing`_ +Attributes: :ref:`Id` +Children: :ref:`Compatibility`, :ref:`Discovery`, :ref:`General`, :ref:`Internal|Unsupported`, :ref:`Partitioning`, :ref:`SSL`, :ref:`Security|DDSSecurity`, :ref:`SharedMemory`, :ref:`Sizing`, :ref:`TCP`, :ref:`Threads`, :ref:`Tracing` The General element specifying Domain related settings. @@ -44,7 +44,7 @@ The default value is: ``any`` //CycloneDDS/Domain/Compatibility ================================= -Children: `//CycloneDDS/Domain/Compatibility/AssumeRtiHasPmdEndpoints`_, `//CycloneDDS/Domain/Compatibility/ExplicitlyPublishQosSetToDefault`_, `//CycloneDDS/Domain/Compatibility/ManySocketsMode`_, `//CycloneDDS/Domain/Compatibility/StandardsConformance`_ +Children: :ref:`AssumeRtiHasPmdEndpoints`, :ref:`ExplicitlyPublishQosSetToDefault`, :ref:`ManySocketsMode`, :ref:`StandardsConformance` The Compatibility element allows you to specify various settings related to compatibility with standards and with other DDSI implementations. @@ -112,7 +112,7 @@ The default value is: ``lax`` //CycloneDDS/Domain/Discovery ============================= -Children: `//CycloneDDS/Domain/Discovery/DSGracePeriod`_, `//CycloneDDS/Domain/Discovery/DefaultMulticastAddress`_, `//CycloneDDS/Domain/Discovery/EnableTopicDiscoveryEndpoints`_, `//CycloneDDS/Domain/Discovery/ExternalDomainId`_, `//CycloneDDS/Domain/Discovery/LeaseDuration`_, `//CycloneDDS/Domain/Discovery/MaxAutoParticipantIndex`_, `//CycloneDDS/Domain/Discovery/ParticipantIndex`_, `//CycloneDDS/Domain/Discovery/Peers`_, `//CycloneDDS/Domain/Discovery/Ports`_, `//CycloneDDS/Domain/Discovery/SPDPInterval`_, `//CycloneDDS/Domain/Discovery/SPDPMulticastAddress`_, `//CycloneDDS/Domain/Discovery/Tag`_ +Children: :ref:`DSGracePeriod`, :ref:`DefaultMulticastAddress`, :ref:`EnableTopicDiscoveryEndpoints`, :ref:`ExternalDomainId`, :ref:`LeaseDuration`, :ref:`MaxAutoParticipantIndex`, :ref:`ParticipantIndex`, :ref:`Peers`, :ref:`Ports`, :ref:`SPDPInterval`, :ref:`SPDPMulticastAddress`, :ref:`Tag` The Discovery element allows you to specify various parameters related to the discovery of peers. @@ -215,7 +215,7 @@ The default value is: ``none`` //CycloneDDS/Domain/Discovery/Peers ----------------------------------- -Children: `//CycloneDDS/Domain/Discovery/Peers/Peer`_ +Children: :ref:`Peer` This element statically configures addresses for discovery. @@ -225,7 +225,7 @@ This element statically configures addresses for discovery. //CycloneDDS/Domain/Discovery/Peers/Peer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [Address](`//CycloneDDS/Domain/Discovery/Peers/Peer[@Address]`_) +Attributes: :ref:`Address` This element statically configures addresses for discovery. @@ -247,7 +247,7 @@ The default value is: ```` //CycloneDDS/Domain/Discovery/Ports ----------------------------------- -Children: `//CycloneDDS/Domain/Discovery/Ports/Base`_, `//CycloneDDS/Domain/Discovery/Ports/DomainGain`_, `//CycloneDDS/Domain/Discovery/Ports/MulticastDataOffset`_, `//CycloneDDS/Domain/Discovery/Ports/MulticastMetaOffset`_, `//CycloneDDS/Domain/Discovery/Ports/ParticipantGain`_, `//CycloneDDS/Domain/Discovery/Ports/UnicastDataOffset`_, `//CycloneDDS/Domain/Discovery/Ports/UnicastMetaOffset`_ +Children: :ref:`Base`, :ref:`DomainGain`, :ref:`MulticastDataOffset`, :ref:`MulticastMetaOffset`, :ref:`ParticipantGain`, :ref:`UnicastDataOffset`, :ref:`UnicastMetaOffset` The Ports element specifies various parameters related to the port numbers used for discovery. These all have default values specified by the DDSI 2.1 specification and rarely need to be changed. @@ -379,7 +379,7 @@ The default value is: ```` //CycloneDDS/Domain/General =========================== -Children: `//CycloneDDS/Domain/General/AllowMulticast`_, `//CycloneDDS/Domain/General/DontRoute`_, `//CycloneDDS/Domain/General/EnableMulticastLoopback`_, `//CycloneDDS/Domain/General/EntityAutoNaming`_, `//CycloneDDS/Domain/General/ExternalNetworkAddress`_, `//CycloneDDS/Domain/General/ExternalNetworkMask`_, `//CycloneDDS/Domain/General/FragmentSize`_, `//CycloneDDS/Domain/General/Interfaces`_, `//CycloneDDS/Domain/General/MaxMessageSize`_, `//CycloneDDS/Domain/General/MaxRexmitMessageSize`_, `//CycloneDDS/Domain/General/MulticastRecvNetworkInterfaceAddresses`_, `//CycloneDDS/Domain/General/MulticastTimeToLive`_, `//CycloneDDS/Domain/General/RedundantNetworking`_, `//CycloneDDS/Domain/General/Transport`_, `//CycloneDDS/Domain/General/UseIPv6`_ +Children: :ref:`AllowMulticast`, :ref:`DontRoute`, :ref:`EnableMulticastLoopback`, :ref:`EntityAutoNaming`, :ref:`ExternalNetworkAddress`, :ref:`ExternalNetworkMask`, :ref:`FragmentSize`, :ref:`Interfaces`, :ref:`MaxMessageSize`, :ref:`MaxRexmitMessageSize`, :ref:`MulticastRecvNetworkInterfaceAddresses`, :ref:`MulticastTimeToLive`, :ref:`RedundantNetworking`, :ref:`Transport`, :ref:`UseIPv6` The General element specifies overall Cyclone DDS service settings. @@ -441,7 +441,7 @@ The default value is: ``true`` //CycloneDDS/Domain/General/EntityAutoNaming -------------------------------------------- -Attributes: [seed](`//CycloneDDS/Domain/General/EntityAutoNaming[@seed]`_) +Attributes: :ref:`seed` One of: empty, fancy @@ -505,7 +505,7 @@ The default value is: ``1344 B`` //CycloneDDS/Domain/General/Interfaces -------------------------------------- -Children: `//CycloneDDS/Domain/General/Interfaces/NetworkInterface`_, `//CycloneDDS/Domain/General/Interfaces/PubSubMessageExchange`_ +Children: :ref:`NetworkInterface`, :ref:`PubSubMessageExchange` This element specifies the network interfaces for use by Cyclone DDS. Multiple interfaces can be specified with an assigned priority. The list in use will be sorted by priority. If interfaces have an equal priority, the specification order will be preserved. @@ -515,7 +515,7 @@ This element specifies the network interfaces for use by Cyclone DDS. Multiple i //CycloneDDS/Domain/General/Interfaces/NetworkInterface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [address](`//CycloneDDS/Domain/General/Interfaces/NetworkInterface[@address]`_), [autodetermine](`//CycloneDDS/Domain/General/Interfaces/NetworkInterface[@autodetermine]`_), [multicast](`//CycloneDDS/Domain/General/Interfaces/NetworkInterface[@multicast]`_), [name](`//CycloneDDS/Domain/General/Interfaces/NetworkInterface[@name]`_), [prefer_multicast](`//CycloneDDS/Domain/General/Interfaces/NetworkInterface[@prefer_multicast]`_), [presence_required](`//CycloneDDS/Domain/General/Interfaces/NetworkInterface[@presence_required]`_), [priority](`//CycloneDDS/Domain/General/Interfaces/NetworkInterface[@priority]`_) +Attributes: :ref:`address`, :ref:`autodetermine`, :ref:`multicast`, :ref:`name`, :ref:`prefer_multicast`, :ref:`presence_required`, :ref:`priority` This element defines a network interface. You can set autodetermine="true" to autoselect the interface CycloneDDS considers the highest quality. If autodetermine="false" (the default), you must specify the name and/or address attribute. If you specify both, they must match the same interface. @@ -609,7 +609,7 @@ The default value is: ``default`` //CycloneDDS/Domain/General/Interfaces/PubSubMessageExchange ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [config](`//CycloneDDS/Domain/General/Interfaces/PubSubMessageExchange[@config]`_), [library](`//CycloneDDS/Domain/General/Interfaces/PubSubMessageExchange[@library]`_), [name](`//CycloneDDS/Domain/General/Interfaces/PubSubMessageExchange[@name]`_), [priority](`//CycloneDDS/Domain/General/Interfaces/PubSubMessageExchange[@priority]`_) +Attributes: :ref:`config`, :ref:`library`, :ref:`name`, :ref:`priority` This element defines a PSMX. @@ -773,7 +773,7 @@ The default value is: ``default`` //CycloneDDS/Domain/Internal ============================ -Children: `//CycloneDDS/Domain/Internal/AccelerateRexmitBlockSize`_, `//CycloneDDS/Domain/Internal/AckDelay`_, `//CycloneDDS/Domain/Internal/AutoReschedNackDelay`_, `//CycloneDDS/Domain/Internal/BuiltinEndpointSet`_, `//CycloneDDS/Domain/Internal/BurstSize`_, `//CycloneDDS/Domain/Internal/ControlTopic`_, `//CycloneDDS/Domain/Internal/DefragReliableMaxSamples`_, `//CycloneDDS/Domain/Internal/DefragUnreliableMaxSamples`_, `//CycloneDDS/Domain/Internal/DeliveryQueueMaxSamples`_, `//CycloneDDS/Domain/Internal/EnableExpensiveChecks`_, `//CycloneDDS/Domain/Internal/GenerateKeyhash`_, `//CycloneDDS/Domain/Internal/HeartbeatInterval`_, `//CycloneDDS/Domain/Internal/LateAckMode`_, `//CycloneDDS/Domain/Internal/LivelinessMonitoring`_, `//CycloneDDS/Domain/Internal/MaxParticipants`_, `//CycloneDDS/Domain/Internal/MaxQueuedRexmitBytes`_, `//CycloneDDS/Domain/Internal/MaxQueuedRexmitMessages`_, `//CycloneDDS/Domain/Internal/MaxSampleSize`_, `//CycloneDDS/Domain/Internal/MeasureHbToAckLatency`_, `//CycloneDDS/Domain/Internal/MonitorPort`_, `//CycloneDDS/Domain/Internal/MultipleReceiveThreads`_, `//CycloneDDS/Domain/Internal/NackDelay`_, `//CycloneDDS/Domain/Internal/PreEmptiveAckDelay`_, `//CycloneDDS/Domain/Internal/PrimaryReorderMaxSamples`_, `//CycloneDDS/Domain/Internal/PrioritizeRetransmit`_, `//CycloneDDS/Domain/Internal/RediscoveryBlacklistDuration`_, `//CycloneDDS/Domain/Internal/RetransmitMerging`_, `//CycloneDDS/Domain/Internal/RetransmitMergingPeriod`_, `//CycloneDDS/Domain/Internal/RetryOnRejectBestEffort`_, `//CycloneDDS/Domain/Internal/SPDPResponseMaxDelay`_, `//CycloneDDS/Domain/Internal/SecondaryReorderMaxSamples`_, `//CycloneDDS/Domain/Internal/SocketReceiveBufferSize`_, `//CycloneDDS/Domain/Internal/SocketSendBufferSize`_, `//CycloneDDS/Domain/Internal/SquashParticipants`_, `//CycloneDDS/Domain/Internal/SynchronousDeliveryLatencyBound`_, `//CycloneDDS/Domain/Internal/SynchronousDeliveryPriorityThreshold`_, `//CycloneDDS/Domain/Internal/Test`_, `//CycloneDDS/Domain/Internal/UnicastResponseToSPDPMessages`_, `//CycloneDDS/Domain/Internal/UseMulticastIfMreqn`_, `//CycloneDDS/Domain/Internal/Watermarks`_, `//CycloneDDS/Domain/Internal/WriterLingerDuration`_ +Children: :ref:`AccelerateRexmitBlockSize`, :ref:`AckDelay`, :ref:`AutoReschedNackDelay`, :ref:`BuiltinEndpointSet`, :ref:`BurstSize`, :ref:`ControlTopic`, :ref:`DefragReliableMaxSamples`, :ref:`DefragUnreliableMaxSamples`, :ref:`DeliveryQueueMaxSamples`, :ref:`EnableExpensiveChecks`, :ref:`GenerateKeyhash`, :ref:`HeartbeatInterval`, :ref:`LateAckMode`, :ref:`LivelinessMonitoring`, :ref:`MaxParticipants`, :ref:`MaxQueuedRexmitBytes`, :ref:`MaxQueuedRexmitMessages`, :ref:`MaxSampleSize`, :ref:`MeasureHbToAckLatency`, :ref:`MonitorPort`, :ref:`MultipleReceiveThreads`, :ref:`NackDelay`, :ref:`PreEmptiveAckDelay`, :ref:`PrimaryReorderMaxSamples`, :ref:`PrioritizeRetransmit`, :ref:`RediscoveryBlacklistDuration`, :ref:`RetransmitMerging`, :ref:`RetransmitMergingPeriod`, :ref:`RetryOnRejectBestEffort`, :ref:`SPDPResponseMaxDelay`, :ref:`SecondaryReorderMaxSamples`, :ref:`SocketReceiveBufferSize`, :ref:`SocketSendBufferSize`, :ref:`SquashParticipants`, :ref:`SynchronousDeliveryLatencyBound`, :ref:`SynchronousDeliveryPriorityThreshold`, :ref:`Test`, :ref:`UnicastResponseToSPDPMessages`, :ref:`UseMulticastIfMreqn`, :ref:`Watermarks`, :ref:`WriterLingerDuration` The Internal elements deal with a variety of settings that are evolving and that are not necessarily fully supported. For the majority of the Internal settings the functionality is supported, but the right to change the way the options control the functionality is reserved. This includes renaming or moving options. @@ -843,7 +843,7 @@ The default value is: ``writers`` //CycloneDDS/Domain/Internal/BurstSize -------------------------------------- -Children: `//CycloneDDS/Domain/Internal/BurstSize/MaxFragsRexmitSample`_, `//CycloneDDS/Domain/Internal/BurstSize/MaxInitTransmit`_, `//CycloneDDS/Domain/Internal/BurstSize/MaxRexmit`_ +Children: :ref:`MaxFragsRexmitSample`, :ref:`MaxInitTransmit`, :ref:`MaxRexmit` Setting for controlling the size of transmitting bursts. @@ -971,7 +971,7 @@ The default value is: ``false`` //CycloneDDS/Domain/Internal/HeartbeatInterval ---------------------------------------------- -Attributes: [max](`//CycloneDDS/Domain/Internal/HeartbeatInterval[@max]`_), [min](`//CycloneDDS/Domain/Internal/HeartbeatInterval[@min]`_), [minsched](`//CycloneDDS/Domain/Internal/HeartbeatInterval[@minsched]`_) +Attributes: :ref:`max`, :ref:`min`, :ref:`minsched` Number-with-unit @@ -1041,7 +1041,7 @@ The default value is: ``false`` //CycloneDDS/Domain/Internal/LivelinessMonitoring ------------------------------------------------- -Attributes: [Interval](`//CycloneDDS/Domain/Internal/LivelinessMonitoring[@Interval]`_), [StackTraces](`//CycloneDDS/Domain/Internal/LivelinessMonitoring[@StackTraces]`_) +Attributes: :ref:`Interval`, :ref:`StackTraces` Boolean @@ -1157,7 +1157,7 @@ The default value is: ``-1`` //CycloneDDS/Domain/Internal/MultipleReceiveThreads --------------------------------------------------- -Attributes: [maxretries](`//CycloneDDS/Domain/Internal/MultipleReceiveThreads[@maxretries]`_) +Attributes: :ref:`maxretries` One of: false, true, default @@ -1235,7 +1235,7 @@ The default value is: ``true`` //CycloneDDS/Domain/Internal/RediscoveryBlacklistDuration --------------------------------------------------------- -Attributes: [enforce](`//CycloneDDS/Domain/Internal/RediscoveryBlacklistDuration[@enforce]`_) +Attributes: :ref:`enforce` Number-with-unit @@ -1337,7 +1337,7 @@ The default value is: ``128`` //CycloneDDS/Domain/Internal/SocketReceiveBufferSize ---------------------------------------------------- -Attributes: [max](`//CycloneDDS/Domain/Internal/SocketReceiveBufferSize[@max]`_), [min](`//CycloneDDS/Domain/Internal/SocketReceiveBufferSize[@min]`_) +Attributes: :ref:`max`, :ref:`min` The settings in this element control the size of the socket receive buffers. The operating system provides some size receive buffer upon creation of the socket, this option can be used to increase the size of the buffer beyond that initially provided by the operating system. If the buffer size cannot be increased to the requested minimum size, an error is reported. @@ -1377,7 +1377,7 @@ The default value is: ``default`` //CycloneDDS/Domain/Internal/SocketSendBufferSize ------------------------------------------------- -Attributes: [max](`//CycloneDDS/Domain/Internal/SocketSendBufferSize[@max]`_), [min](`//CycloneDDS/Domain/Internal/SocketSendBufferSize[@min]`_) +Attributes: :ref:`max`, :ref:`min` The settings in this element control the size of the socket send buffers. The operating system provides some size send buffer upon creation of the socket, this option can be used to increase the size of the buffer beyond that initially provided by the operating system. If the buffer size cannot be increased to the requested minimum size, an error is reported. @@ -1455,7 +1455,7 @@ The default value is: ``0`` //CycloneDDS/Domain/Internal/Test --------------------------------- -Children: `//CycloneDDS/Domain/Internal/Test/XmitLossiness`_ +Children: :ref:`XmitLossiness` Testing options. @@ -1501,7 +1501,7 @@ The default value is: ``0`` //CycloneDDS/Domain/Internal/Watermarks --------------------------------------- -Children: `//CycloneDDS/Domain/Internal/Watermarks/WhcAdaptive`_, `//CycloneDDS/Domain/Internal/Watermarks/WhcHigh`_, `//CycloneDDS/Domain/Internal/Watermarks/WhcHighInit`_, `//CycloneDDS/Domain/Internal/Watermarks/WhcLow`_ +Children: :ref:`WhcAdaptive|WhcAdaptative`, :ref:`WhcHigh`, :ref:`WhcHighInit`, :ref:`WhcLow` Watermarks for flow-control. @@ -1578,7 +1578,7 @@ The default value is: ``1 s`` //CycloneDDS/Domain/Partitioning ================================ -Children: `//CycloneDDS/Domain/Partitioning/IgnoredPartitions`_, `//CycloneDDS/Domain/Partitioning/NetworkPartitions`_, `//CycloneDDS/Domain/Partitioning/PartitionMappings`_ +Children: :ref:`IgnoredPartitions`, :ref:`NetworkPartitions`, :ref:`PartitionMappings` The Partitioning element specifies Cyclone DDS network partitions and how DCPS partition/topic combinations are mapped onto the network partitions. @@ -1588,7 +1588,7 @@ The Partitioning element specifies Cyclone DDS network partitions and how DCPS p //CycloneDDS/Domain/Partitioning/IgnoredPartitions -------------------------------------------------- -Children: `//CycloneDDS/Domain/Partitioning/IgnoredPartitions/IgnoredPartition`_ +Children: :ref:`IgnoredPartition` The IgnoredPartitions element specifies DCPS partition/topic combinations that are not distributed over the network. @@ -1598,7 +1598,7 @@ The IgnoredPartitions element specifies DCPS partition/topic combinations that a //CycloneDDS/Domain/Partitioning/IgnoredPartitions/IgnoredPartition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [DCPSPartitionTopic](`//CycloneDDS/Domain/Partitioning/IgnoredPartitions/IgnoredPartition[@DCPSPartitionTopic]`_) +Attributes: :ref:`DCPSPartitionTopic` Text @@ -1624,7 +1624,7 @@ The default value is: ```` //CycloneDDS/Domain/Partitioning/NetworkPartitions -------------------------------------------------- -Children: `//CycloneDDS/Domain/Partitioning/NetworkPartitions/NetworkPartition`_ +Children: :ref:`NetworkPartition` The NetworkPartitions element specifies the Cyclone DDS network partitions. @@ -1634,7 +1634,7 @@ The NetworkPartitions element specifies the Cyclone DDS network partitions. //CycloneDDS/Domain/Partitioning/NetworkPartitions/NetworkPartition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [Address](`//CycloneDDS/Domain/Partitioning/NetworkPartitions/NetworkPartition[@Address]`_), [Interface](`//CycloneDDS/Domain/Partitioning/NetworkPartitions/NetworkPartition[@Interface]`_), [Name](`//CycloneDDS/Domain/Partitioning/NetworkPartitions/NetworkPartition[@Name]`_) +Attributes: :ref:`Address`, :ref:`Interface`, :ref:`Name` Text @@ -1689,7 +1689,7 @@ The default value is: ```` //CycloneDDS/Domain/Partitioning/PartitionMappings -------------------------------------------------- -Children: `//CycloneDDS/Domain/Partitioning/PartitionMappings/PartitionMapping`_ +Children: :ref:`PartitionMapping` The PartitionMappings element specifies the mapping from DCPS partition/topic combinations to Cyclone DDS network partitions. @@ -1699,7 +1699,7 @@ The PartitionMappings element specifies the mapping from DCPS partition/topic co //CycloneDDS/Domain/Partitioning/PartitionMappings/PartitionMapping ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [DCPSPartitionTopic](`//CycloneDDS/Domain/Partitioning/PartitionMappings/PartitionMapping[@DCPSPartitionTopic]`_), [NetworkPartition](`//CycloneDDS/Domain/Partitioning/PartitionMappings/PartitionMapping[@NetworkPartition]`_) +Attributes: :ref:`DCPSPartitionTopic`, :ref:`NetworkPartition` Text @@ -1737,7 +1737,7 @@ The default value is: ```` //CycloneDDS/Domain/SSL ======================= -Children: `//CycloneDDS/Domain/SSL/CertificateVerification`_, `//CycloneDDS/Domain/SSL/Ciphers`_, `//CycloneDDS/Domain/SSL/Enable`_, `//CycloneDDS/Domain/SSL/EntropyFile`_, `//CycloneDDS/Domain/SSL/KeyPassphrase`_, `//CycloneDDS/Domain/SSL/KeystoreFile`_, `//CycloneDDS/Domain/SSL/MinimumTLSVersion`_, `//CycloneDDS/Domain/SSL/SelfSignedCertificates`_, `//CycloneDDS/Domain/SSL/VerifyClient`_ +Children: :ref:`CertificateVerification`, :ref:`Ciphers`, :ref:`Enable`, :ref:`EntropyFile`, :ref:`KeyPassphrase`, :ref:`KeystoreFile`, :ref:`MinimumTLSVersion`, :ref:`SelfSignedCertificates`, :ref:`VerifyClient` The SSL element allows specifying various parameters related to using SSL/TLS for DDSI over TCP. @@ -1855,7 +1855,7 @@ The default value is: ``true`` //CycloneDDS/Domain/Security ============================ -Children: `//CycloneDDS/Domain/Security/AccessControl`_, `//CycloneDDS/Domain/Security/Authentication`_, `//CycloneDDS/Domain/Security/Cryptographic`_ +Children: :ref:`AccessControl`, :ref:`Authentication`, :ref:`Cryptographic` This element is used to configure Cyclone DDS with the DDS Security specification plugins and settings. @@ -1865,7 +1865,7 @@ This element is used to configure Cyclone DDS with the DDS Security specificatio //CycloneDDS/Domain/Security/AccessControl ------------------------------------------ -Children: `//CycloneDDS/Domain/Security/AccessControl/Governance`_, `//CycloneDDS/Domain/Security/AccessControl/Library`_, `//CycloneDDS/Domain/Security/AccessControl/Permissions`_, `//CycloneDDS/Domain/Security/AccessControl/PermissionsCA`_ +Children: :ref:`Governance`, :ref:`Library`, :ref:`Permissions`, :ref:`PermissionsCA` This element configures the Access Control plugin of the DDS Security specification. @@ -1929,7 +1929,7 @@ The default value is: ```` //CycloneDDS/Domain/Security/AccessControl/Library ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [finalizeFunction](`//CycloneDDS/Domain/Security/AccessControl/Library[@finalizeFunction]`_), [initFunction](`//CycloneDDS/Domain/Security/AccessControl/Library[@initFunction]`_), [path](`//CycloneDDS/Domain/Security/AccessControl/Library[@path]`_) +Attributes: :ref:`finalizeFunction`, :ref:`initFunction`, :ref:`path` Text @@ -2031,7 +2031,7 @@ The default value is: ```` //CycloneDDS/Domain/Security/Authentication ------------------------------------------- -Children: `//CycloneDDS/Domain/Security/Authentication/CRL`_, `//CycloneDDS/Domain/Security/Authentication/IdentityCA`_, `//CycloneDDS/Domain/Security/Authentication/IdentityCertificate`_, `//CycloneDDS/Domain/Security/Authentication/IncludeOptionalFields`_, `//CycloneDDS/Domain/Security/Authentication/Library`_, `//CycloneDDS/Domain/Security/Authentication/Password`_, `//CycloneDDS/Domain/Security/Authentication/PrivateKey`_, `//CycloneDDS/Domain/Security/Authentication/TrustedCADirectory`_ +Children: :ref:`CRL`, :ref:`IdentityCA`, :ref:`IdentityCertificate`, :ref:`IncludeOptionalFields`, :ref:`Library`, :ref:`Password`, :ref:`PrivateKey`, :ref:`TrustedCADirectory` This element configures the Authentication plugin of the DDS Security specification. @@ -2121,7 +2121,7 @@ The default value is: ``false`` //CycloneDDS/Domain/Security/Authentication/Library ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [finalizeFunction](`//CycloneDDS/Domain/Security/Authentication/Library[@finalizeFunction]`_), [initFunction](`//CycloneDDS/Domain/Security/Authentication/Library[@initFunction]`_), [path](`//CycloneDDS/Domain/Security/Authentication/Library[@path]`_) +Attributes: :ref:`finalizeFunction`, :ref:`initFunction`, :ref:`path` Text @@ -2225,7 +2225,7 @@ The default value is: ```` //CycloneDDS/Domain/Security/Cryptographic ------------------------------------------ -Children: `//CycloneDDS/Domain/Security/Cryptographic/Library`_ +Children: :ref:`Library` This element configures the Cryptographic plugin of the DDS Security specification. @@ -2235,7 +2235,7 @@ This element configures the Cryptographic plugin of the DDS Security specificati //CycloneDDS/Domain/Security/Cryptographic/Library ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes: [finalizeFunction](`//CycloneDDS/Domain/Security/Cryptographic/Library[@finalizeFunction]`_), [initFunction](`//CycloneDDS/Domain/Security/Cryptographic/Library[@initFunction]`_), [path](`//CycloneDDS/Domain/Security/Cryptographic/Library[@path]`_) +Attributes: :ref:`finalizeFunction`, :ref:`initFunction`, :ref:`path` Text @@ -2297,7 +2297,7 @@ The Shared Memory element allows specifying various parameters related to using //CycloneDDS/Domain/Sizing ========================== -Children: `//CycloneDDS/Domain/Sizing/ReceiveBufferChunkSize`_, `//CycloneDDS/Domain/Sizing/ReceiveBufferSize`_ +Children: :ref:`ReceiveBufferChunkSize`, :ref:`ReceiveBufferSize` The Sizing element allows you to specify various configuration settings dealing with expected system sizes, buffer sizes, &c. @@ -2335,7 +2335,7 @@ The default value is: ``1 MiB`` //CycloneDDS/Domain/TCP ======================= -Children: `//CycloneDDS/Domain/TCP/AlwaysUsePeeraddrForUnicast`_, `//CycloneDDS/Domain/TCP/Enable`_, `//CycloneDDS/Domain/TCP/NoDelay`_, `//CycloneDDS/Domain/TCP/Port`_, `//CycloneDDS/Domain/TCP/ReadTimeout`_, `//CycloneDDS/Domain/TCP/WriteTimeout`_ +Children: :ref:`AlwaysUsePeeraddrForUnicast`, :ref:`Enable`, :ref:`NoDelay`, :ref:`Port`, :ref:`ReadTimeout`, :ref:`WriteTimeout` The TCP element allows you to specify various parameters related to running DDSI over TCP. @@ -2421,7 +2421,7 @@ The default value is: ``2 s`` //CycloneDDS/Domain/Threads =========================== -Children: `//CycloneDDS/Domain/Threads/Thread`_ +Children: :ref:`Thread` This element is used to set thread properties. @@ -2431,8 +2431,8 @@ This element is used to set thread properties. //CycloneDDS/Domain/Threads/Thread ---------------------------------- -Attributes: [Name](`//CycloneDDS/Domain/Threads/Thread[@Name]`_) -Children: `//CycloneDDS/Domain/Threads/Thread/Scheduling`_, `//CycloneDDS/Domain/Threads/Thread/StackSize`_ +Attributes: :ref:`Name` +Children: :ref:`Scheduling`, :ref:`StackSize` This element is used to set thread properties. @@ -2473,7 +2473,7 @@ The default value is: ```` //CycloneDDS/Domain/Threads/Thread/Scheduling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Children: `//CycloneDDS/Domain/Threads/Thread/Scheduling/Class`_, `//CycloneDDS/Domain/Threads/Thread/Scheduling/Priority`_ +Children: :ref:`Class`, :ref:`Priority` This element configures the scheduling properties of the thread. @@ -2521,7 +2521,7 @@ The default value is: ``default`` //CycloneDDS/Domain/Tracing =========================== -Children: `//CycloneDDS/Domain/Tracing/AppendToFile`_, `//CycloneDDS/Domain/Tracing/Category`_, `//CycloneDDS/Domain/Tracing/OutputFile`_, `//CycloneDDS/Domain/Tracing/PacketCaptureFile`_, `//CycloneDDS/Domain/Tracing/Verbosity`_ +Children: :ref:`AppendToFile`, :ref:`Category|EnableCategory`, :ref:`OutputFile`, :ref:`PacketCaptureFile`, :ref:`Verbosity` The Tracing element controls the amount and type of information that is written into the tracing log by the DDSI service. This is useful to track the DDSI service during application development. @@ -2648,6 +2648,6 @@ The default value is: ``none`` generated from _confgen.c[237308acd53897a34e8c643e16e05a61d73ffd65] generated from generate_rnc.c[b50e4b7ab1d04b2bc1d361a0811247c337b74934] generated from generate_md.c[789b92e422631684352909cfb8bf43f6ceb16a01] - generated from generate_rst.c[c35cdcdfc0bd4f10a801204a6cc5d540af696b6e] + generated from generate_rst.c[3c4b523fbb57c8e4a7e247379d06a8021ccc21c4] generated from generate_xsd.c[6b6818d7f17a35d56c376c04ec1410427f34c0f0] generated from generate_defconfig.c[63ca9d8ae2f1ce2e761c9d4c0510a45eb062d830] diff --git a/docs/manual/ddsc.rst b/docs/manual/ddsc.rst index 50070721c9..d0b2e0d31a 100644 --- a/docs/manual/ddsc.rst +++ b/docs/manual/ddsc.rst @@ -31,3 +31,5 @@ C API reference api/serialization api/internal api/deprecated + api/psmx + api/dynamic diff --git a/docs/manual/doxygen.conf.in b/docs/manual/doxygen.conf.in index 939f38b732..152ef282d6 100644 --- a/docs/manual/doxygen.conf.in +++ b/docs/manual/doxygen.conf.in @@ -11,7 +11,7 @@ WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = YES WARN_AS_ERROR = NO -INPUT = ../../src/core/ddsc/include/dds/ ../../src/ddsrt/include/dds/ddsrt/retcode.h +INPUT = ../../src/core/ddsc/include/dds/ ../../src/ddsrt/include/dds/ddsrt/retcode.h ../../src/ddsrt/include/dds/ddsrt/log.h FILE_PATTERNS = *.c *.idl **.h RECURSIVE = YES EXCLUDE_SYMLINKS = NO diff --git a/docs/manual/options.md b/docs/manual/options.md index 1071cd05f1..e6f33ec4a9 100644 --- a/docs/manual/options.md +++ b/docs/manual/options.md @@ -1852,6 +1852,6 @@ The default value is: `none` - + diff --git a/docs/manual/shared_memory/shared_mem_config.rst b/docs/manual/shared_memory/shared_mem_config.rst index 474059cc21..aefac95b99 100644 --- a/docs/manual/shared_memory/shared_mem_config.rst +++ b/docs/manual/shared_memory/shared_mem_config.rst @@ -63,33 +63,8 @@ The location where |var-project-short| looks for the config file is set through export CYCLONEDDS_URI=file://cyclonedds.xml -The following optional configuration parameters in SharedMemory govern how |var-project-short| treats shared memory: - -* Enable - - * When set to *true* enables |var-project-short| to use shared memory for local data exchange - - * Defaults to *false* - -* LogLevel - - * Controls the output of the iceoryx runtime and can be set to, in order of decreasing output: - - * *verbose* - - * *debug* - - * *info* (default) - - * *warn* - - * *error* - - * *fatal* - - * *off* - -The following is an example of a |var-project-short| configuration file supporting shared memory exchange: +The following is an example of a |var-project-short| configuration file supporting shared memory exchange through iceoryx. +Please check :ref:`//CycloneDDS/Domain/General/Interfaces/PubSubMessageExchange` for all configuration details. .. code-block:: xml @@ -98,10 +73,11 @@ The following is an example of a |var-project-short| configuration file supporti xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://cdds.io/config https://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/iceoryx/etc/cyclonedds.xsd"> - - true - info - + + + + + diff --git a/docs/manual/shared_memory/shared_memory.rst b/docs/manual/shared_memory/shared_memory.rst index 20566668b0..19884f78d8 100644 --- a/docs/manual/shared_memory/shared_memory.rst +++ b/docs/manual/shared_memory/shared_memory.rst @@ -42,7 +42,7 @@ Prerequisites git clone https://github.com/eclipse-iceoryx/iceoryx.git -b release_2.0 cd iceoryx - cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install -DBUILD_SHARED_LIBS=ON -Hiceoryx_meta + cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install -DROUDI_ENVIRONMENT=on -DBUILD_SHARED_LIBS=ON -Hiceoryx_meta cmake --build build --config Release --target install #. Get |var-project-short| and build it with shared memory support: @@ -51,7 +51,7 @@ Prerequisites git clone https://github.com/eclipse-cyclonedds/cyclonedds.git cd cyclonedds - cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install -DBUILD_EXAMPLES=On -DCMAKE_PREFIX_PATH=~/iceoryx/install/ + cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install -DENABLE_ICEORYX=On -DBUILD_EXAMPLES=On -DCMAKE_PREFIX_PATH=~/iceoryx/install/ cmake --build build --config Release --target install When the compiler has finished, the files for both iceoryx and |var-project-short| can diff --git a/etc/cyclonedds.rnc b/etc/cyclonedds.rnc index b1e1438071..03fe0317c8 100644 --- a/etc/cyclonedds.rnc +++ b/etc/cyclonedds.rnc @@ -1291,6 +1291,6 @@ MIIEpAIBAAKCAQEA3HIh...AOBaaqSV37XBUJg==
# generated from _confgen.c[237308acd53897a34e8c643e16e05a61d73ffd65] # generated from generate_rnc.c[b50e4b7ab1d04b2bc1d361a0811247c337b74934] # generated from generate_md.c[789b92e422631684352909cfb8bf43f6ceb16a01] -# generated from generate_rst.c[c35cdcdfc0bd4f10a801204a6cc5d540af696b6e] +# generated from generate_rst.c[3c4b523fbb57c8e4a7e247379d06a8021ccc21c4] # generated from generate_xsd.c[6b6818d7f17a35d56c376c04ec1410427f34c0f0] # generated from generate_defconfig.c[63ca9d8ae2f1ce2e761c9d4c0510a45eb062d830] diff --git a/etc/cyclonedds.xsd b/etc/cyclonedds.xsd index 0ecd10e6ab..5f8a20bb86 100644 --- a/etc/cyclonedds.xsd +++ b/etc/cyclonedds.xsd @@ -1947,6 +1947,6 @@ MIIEpAIBAAKCAQEA3HIh...AOBaaqSV37XBUJg==<br> - + diff --git a/src/core/ddsc/include/dds/dds.h b/src/core/ddsc/include/dds/dds.h index 5a7484683a..a9be3535db 100644 --- a/src/core/ddsc/include/dds/dds.h +++ b/src/core/ddsc/include/dds/dds.h @@ -3086,8 +3086,8 @@ dds_waitset_wait_until( * etc. This continues until it has traversed the entire history cache or has gathered * `maxs` samples. * - * The @ref `dds_read` operation can be used to mark the returned samples as "read"; the - * @ref `dds_take` operation can be used to also remove the returned samples from the + * The @ref dds_read operation can be used to mark the returned samples as "read"; the + * @ref dds_take operation can be used to also remove the returned samples from the * history cache. * * For the plain `dds_peek` operation, all instances and samples match. This is different @@ -3104,7 +3104,7 @@ dds_waitset_wait_until( * - all of `buf[0]` .. `buf[k-1]` must be pointers to outstanding loans; and * - `k` = `bufsz` or `buf[k]` is a null pointer; where * - `1 <= k < bufsz`; and - * - all these outstanding loans are returned as-if through @ref `dds_return_loan`; and + * - all these outstanding loans are returned as-if through @ref dds_return_loan; and * - the result will be as if `buf[0]` had been a null pointer on entry. * * - If `buf[0]` on entry is any other address, then: @@ -3153,7 +3153,7 @@ dds_peek( * @ingroup reading * @component read_data * - * See @ref `dds_peek`. The matching criterion referred to there is that the + * See @ref dds_peek. The matching criterion referred to there is that the * sample/view/instance states must match the specification in the `mask` parameter. * * If the sample/view/instance state component in the mask is 0 and `reader_or_condition` @@ -3196,7 +3196,7 @@ dds_peek_mask( * @ingroup reading * @component read_data * - * See @ref `dds_peek`. The matching criterion referred to there is that the instance + * See @ref dds_peek. The matching criterion referred to there is that the instance * handle must equal the `handle` parameter. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. @@ -3235,7 +3235,7 @@ dds_peek_instance( * @ingroup reading * @component read_data * - * See @ref `dds_peek`. The matching criterion referred to there is that: + * See @ref dds_peek. The matching criterion referred to there is that: * - the instance handle must equal the `handle` parameter; and * - the sample/view/instance states must match the specification in the `mask` parameter. * @@ -3317,8 +3317,8 @@ dds_peek_next( * etc. This continues until it has traversed the entire history cache or has gathered * `maxs` samples. * - * The @ref `dds_peek` operation can be read samples without marking them as "read"; the - * @ref `dds_take` operation can be used to also remove the returned samples from the + * The @ref dds_peek operation can be read samples without marking them as "read"; the + * @ref dds_take operation can be used to also remove the returned samples from the * history cache. * * For the plain `dds_read` operation, all instances and samples match. This is different @@ -3335,7 +3335,7 @@ dds_peek_next( * - all of `buf[0]` .. `buf[k-1]` must be pointers to outstanding loans; and * - `k` = `bufsz` or `buf[k]` is a null pointer; where * - `1 <= k < bufsz`; and - * - all these outstanding loans are returned as-if through @ref `dds_return_loan`; and + * - all these outstanding loans are returned as-if through @ref dds_return_loan; and * - the result will be as if `buf[0]` had been a null pointer on entry. * * - If `buf[0]` on entry is any other address, then: @@ -3416,7 +3416,7 @@ dds_read_wl( * @ingroup reading * @component read_data * - * See @ref `dds_read`. The matching criterion referred to there is that the + * See @ref dds_read. The matching criterion referred to there is that the * sample/view/instance states must match the specification in the `mask` parameter. * * If the sample/view/instance state component in the mask is 0 and `reader_or_condition` @@ -3459,7 +3459,7 @@ dds_read_mask( * @ingroup reading * @component read_data * - * @deprecated Alias for @ref `dds_read_mask` where `bufsz` = `maxs`. + * @deprecated Alias for @ref dds_read_mask where `bufsz` = `maxs`. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[in,out] buf An array of `maxs` pointers to samples. @@ -3493,7 +3493,7 @@ dds_read_mask_wl( * @ingroup reading * @component read_data * - * See @ref `dds_read`. The matching criterion referred to there is that the instance + * See @ref dds_read. The matching criterion referred to there is that the instance * handle must equal the `handle` parameter. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. @@ -3532,7 +3532,7 @@ dds_read_instance( * @ingroup reading * @component read_data * - * @deprecated Alias for @ref `dds_read_instance` where `bufsz` = `maxs`. + * @deprecated Alias for @ref dds_read_instance where `bufsz` = `maxs`. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[in,out] buf An array of `maxs` pointers to samples. @@ -3568,7 +3568,7 @@ dds_read_instance_wl( * @ingroup reading * @component read_data * - * See @ref `dds_read`. The matching criterion referred to there is that: + * See @ref dds_read. The matching criterion referred to there is that: * - the instance handle must equal the `handle` parameter; and * - the sample/view/instance states must match the specification in the `mask` parameter. * @@ -3616,7 +3616,7 @@ dds_read_instance_mask( * @ingroup reading * @component read_data * - * @deprecated Alias for @ref `dds_read_instance_mask` where `bufsz` = `maxs`. + * @deprecated Alias for @ref dds_read_instance_mask where `bufsz` = `maxs`. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[in,out] buf An array of `maxs` pointers to samples. @@ -3682,7 +3682,7 @@ dds_read_next( * @ingroup reading * @component read_data * - * @deprecated Alias for @ref `dds_read_next`. + * @deprecated Alias for @ref dds_read_next. * * @param[in] reader The reader entity. * @param[in,out] buf A pointer to a sample. @@ -3716,8 +3716,8 @@ dds_read_next_wl( * continues until it has traversed the entire history cache or has gathered `maxs` * samples. * - * The @ref `dds_read` operation can be used to read samples without removing them from - * the history cache but marking them as "read"; the @ref `dds_peek` operation can be used + * The @ref dds_read operation can be used to read samples without removing them from + * the history cache but marking them as "read"; the @ref dds_peek operation can be used * to read samples from the cache without changing any internal state. * * For the plain `dds_take` operation, all instances and samples match. This is different @@ -3734,7 +3734,7 @@ dds_read_next_wl( * - all of `buf[0]` .. `buf[k-1]` must be pointers to outstanding loans; and * - `k` = `bufsz` or `buf[k]` is a null pointer; where * - `1 <= k < bufsz`; and - * - all these outstanding loans are returned as-if through @ref `dds_return_loan`; and + * - all these outstanding loans are returned as-if through @ref dds_return_loan; and * - the result will be as if `buf[0]` had been a null pointer on entry. * * - If `buf[0]` on entry is any other address, then: @@ -3783,7 +3783,7 @@ dds_take( * @ingroup reading * @component read_data * - * @deprecated Alias for @ref `dds_take` where `bufsz` = `maxs`. + * @deprecated Alias for @ref dds_take where `bufsz` = `maxs`. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[in,out] buf An array of `maxs` pointers to samples. @@ -3815,7 +3815,7 @@ dds_take_wl( * @ingroup reading * @component read_data * - * See @ref `dds_take`. The matching criterion referred to there is that the + * See @ref dds_take. The matching criterion referred to there is that the * sample/view/instance states must match the specification in the `mask` parameter. * * If the sample/view/instance state component in the mask is 0 and `reader_or_condition` @@ -3892,7 +3892,7 @@ dds_take_mask_wl( * @ingroup reading * @component read_data * - * See @ref `dds_take`. The matching criterion referred to there is that the instance + * See @ref dds_take. The matching criterion referred to there is that the instance * handle must equal the `handle` parameter. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. @@ -3931,7 +3931,7 @@ dds_take_instance( * @ingroup reading * @component read_data * - * @deprecated Alias for @ref `dds_take_instance` where `bufsz` = `maxs`. + * @deprecated Alias for @ref dds_take_instance where `bufsz` = `maxs`. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[in,out] buf An array of `maxs` pointers to samples. @@ -3967,7 +3967,7 @@ dds_take_instance_wl( * @ingroup reading * @component read_data * - * See @ref `dds_take`. The matching criterion referred to there is that: + * See @ref dds_take. The matching criterion referred to there is that: * - the instance handle must equal the `handle` parameter; and * - the sample/view/instance states must match the specification in the `mask` parameter. * @@ -4015,7 +4015,7 @@ dds_take_instance_mask( * @ingroup reading * @component read_data * - * @deprecated Alias for @ref `dds_take_instance_mask` where `bufsz` = `maxs`. + * @deprecated Alias for @ref dds_take_instance_mask where `bufsz` = `maxs`. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[in,out] buf An array of `maxs` pointers to samples. @@ -4081,7 +4081,7 @@ dds_take_next( * @ingroup reading * @component read_data * - * @deprecated Alias for @ref `dds_take_next`. + * @deprecated Alias for @ref dds_take_next. * * @param[in] reader The reader entity. * @param[in,out] buf A pointer to a sample. @@ -4276,10 +4276,10 @@ dds_take_with_collector ( * the application, other options may exist as well. * * The data is left in the reader history cache and the sample state and view state of the returned samples and their - * instances are not updated; @ref `dds_readcdr` updates these states; @ref `dds_takecdr` removes the data + * instances are not updated; @ref dds_readcdr updates these states; @ref dds_takecdr removes the data * from the history cache. * - * The returned references must eventually be released by calling @ref `ddsi_serdata_unref`. There is no guarantee + * The returned references must eventually be released by calling @ref ddsi_serdata_unref. There is no guarantee * the type pointer survives beyond the existence of the reader from which the references were read. * * When using a readcondition or querycondition, their masks are or'd with the given mask. @@ -4287,7 +4287,7 @@ dds_take_with_collector ( * If the sample/view/instance state component in the mask is 0 and there is no read or query condition, * to combine it with, it is treated as equivalent to any sample/view/instance state. * - * Note that this is a simple wrapper around @ref `dds_peek_with_collector`. + * Note that this is a simple wrapper around @ref dds_peek_with_collector. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[out] buf Filled with references @ref ddsi_serdata structures. @@ -4329,10 +4329,10 @@ dds_peekcdr( * the application, other options may exist as well. * * The data is left in the reader history cache and the sample state and view state of the returned samples and their - * instances are not updated; @ref `dds_readcdr` updates these states; @ref `dds_takecdr` removes the data + * instances are not updated; @ref dds_readcdr updates these states; @ref dds_takecdr removes the data * from the history cache. * - * The returned references must eventually be released by calling @ref `ddsi_serdata_unref`. There is no guarantee + * The returned references must eventually be released by calling @ref ddsi_serdata_unref. There is no guarantee * the type pointer survives beyond the existence of the reader from which the references were read. * * When using a readcondition or querycondition, their masks are or'd with the given mask. @@ -4340,7 +4340,7 @@ dds_peekcdr( * If the sample/view/instance state component in the mask is 0 and there is no read or query condition, * to combine it with, it is treated as equivalent to any sample/view/instance state. * - * Note that this is a simple wrapper around @ref `dds_peek_with_collector`. + * Note that this is a simple wrapper around @ref dds_peek_with_collector. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[out] buf Filled with references @ref ddsi_serdata structures. @@ -4384,10 +4384,10 @@ dds_peekcdr_instance ( * the application, other options may exist as well. * * The data is left in the reader history cache and the sample state and view state of the returned samples and their - * instances are updated; @ref `dds_peekcdr` returns the data without updating these states; @ref `dds_takecdr` + * instances are updated; @ref dds_peekcdr returns the data without updating these states; @ref dds_takecdr * removes the data from the history cache. * - * The returned references must eventually be released by calling @ref `ddsi_serdata_unref`. There is no guarantee + * The returned references must eventually be released by calling @ref ddsi_serdata_unref. There is no guarantee * the type pointer survives beyond the existence of the reader from which the references were read. * * When using a readcondition or querycondition, their masks are or'd with the given mask. @@ -4395,7 +4395,7 @@ dds_peekcdr_instance ( * If the sample/view/instance state component in the mask is 0 and there is no read or query condition, * to combine it with, it is treated as equivalent to any sample/view/instance state. * - * Note that this is a simple wrapper around @ref `dds_read_with_collector`. + * Note that this is a simple wrapper around @ref dds_read_with_collector. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[out] buf Filled with references @ref ddsi_serdata structures. @@ -4437,10 +4437,10 @@ dds_readcdr( * the application, other options may exist as well. * * The data is left in the reader history cache and the sample state and view state of the returned samples and their - * instances are updated; @ref `dds_peekcdr` returns the data without updating these states; @ref `dds_takecdr` + * instances are updated; @ref dds_peekcdr returns the data without updating these states; @ref dds_takecdr * removes the data from the history cache. * - * The returned references must eventually be released by calling @ref `ddsi_serdata_unref`. There is no guarantee + * The returned references must eventually be released by calling @ref ddsi_serdata_unref. There is no guarantee * the type pointer survives beyond the existence of the reader from which the references were read. * * When using a readcondition or querycondition, their masks are or'd with the given mask. @@ -4448,7 +4448,7 @@ dds_readcdr( * If the sample/view/instance state component in the mask is 0 and there is no read or query condition, * to combine it with, it is treated as equivalent to any sample/view/instance state. * - * Note that this is a simple wrapper around @ref `dds_read_with_collector`. + * Note that this is a simple wrapper around @ref dds_read_with_collector. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[out] buf Filled with references @ref ddsi_serdata structures. @@ -4491,11 +4491,11 @@ dds_readcdr_instance ( * reference of the serialized representation. If the underlying implementation (`struct ddsi_sertype`) is known to * the application, other options may exist as well. * - * The data is removed from the reader history cache; @ref `dds_peekcdr` leaves them in and leaves the sample and - * view states unchanged; @ref `dds_readcdr` leaves the data in the cache but does update the sample and view + * The data is removed from the reader history cache; @ref dds_peekcdr leaves them in and leaves the sample and + * view states unchanged; @ref dds_readcdr leaves the data in the cache but does update the sample and view * states. * - * The returned references must eventually be released by calling @ref `ddsi_serdata_unref`. There is no guarantee + * The returned references must eventually be released by calling @ref ddsi_serdata_unref. There is no guarantee * the type pointer survives beyond the existence of the reader from which the references were read. * * When using a readcondition or querycondition, their masks are or'd with the given mask. @@ -4503,7 +4503,7 @@ dds_readcdr_instance ( * If the sample/view/instance state component in the mask is 0 and there is no read or query condition, * to combine it with, it is treated as equivalent to any sample/view/instance state. * - * Note that this is a simple wrapper around @ref `dds_take_with_collector`. + * Note that this is a simple wrapper around @ref dds_take_with_collector. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[out] buf Filled with references @ref ddsi_serdata structures. @@ -4544,11 +4544,11 @@ dds_takecdr( * reference of the serialized representation. If the underlying implementation (`struct ddsi_sertype`) is known to * the application, other options may exist as well. * - * The data is removed from the reader history cache; @ref `dds_peekcdr` leaves them in and leaves the sample and - * view states unchanged; @ref `dds_readcdr` leaves the data in the cache but does update the sample and view + * The data is removed from the reader history cache; @ref dds_peekcdr leaves them in and leaves the sample and + * view states unchanged; @ref dds_readcdr leaves the data in the cache but does update the sample and view * states. * - * The returned references must eventually be released by calling @ref `ddsi_serdata_unref`. There is no guarantee + * The returned references must eventually be released by calling @ref ddsi_serdata_unref. There is no guarantee * the type pointer survives beyond the existence of the reader from which the references were read. * * When using a readcondition or querycondition, their masks are or'd with the given mask. @@ -4556,7 +4556,7 @@ dds_takecdr( * If the sample/view/instance state component in the mask is 0 and there is no read or query condition, * to combine it with, it is treated as equivalent to any sample/view/instance state. * - * Note that this is a simple wrapper around @ref `dds_take_with_collector`. + * Note that this is a simple wrapper around @ref dds_take_with_collector. * * @param[in] reader_or_condition Reader, readcondition or querycondition entity. * @param[out] buf Filled with references @ref ddsi_serdata structures. diff --git a/src/core/ddsc/include/dds/ddsc/dds_loaned_sample.h b/src/core/ddsc/include/dds/ddsc/dds_loaned_sample.h index 9ee1bd8d42..cc9469f0bb 100644 --- a/src/core/ddsc/include/dds/ddsc/dds_loaned_sample.h +++ b/src/core/ddsc/include/dds/ddsc/dds_loaned_sample.h @@ -34,6 +34,7 @@ struct dds_psmx_endpoint; /** * @brief State of the data contained in a memory block + * @ingroup loaned_sample */ typedef enum dds_loaned_sample_state { DDS_LOANED_SAMPLE_STATE_UNITIALIZED, @@ -45,11 +46,13 @@ typedef enum dds_loaned_sample_state { /** * @brief Identifier used to distinguish between raw data types (C/C++/Python/...) + * @ingroup loaned_sample */ typedef uint32_t dds_loan_data_type_t; /** * @brief Definition for function to free a loaned sample + * @ingroup loaned_sample * * @param[in] loaned_sample A loaned sample */ @@ -58,6 +61,7 @@ typedef void (*dds_loaned_sample_free_f) (struct dds_loaned_sample *loaned_sampl /** * @brief Container for implementation specific operations + * @ingroup loaned_sample */ typedef struct dds_loaned_sample_ops { dds_loaned_sample_free_f free; @@ -75,6 +79,7 @@ typedef struct dds_loaned_sample_origin { /** * @brief The definition of a block of memory originating from a PSMX + * @ingroup loaned_sample */ typedef struct dds_loaned_sample { dds_loaned_sample_ops_t ops; //!< the implementation specific ops for this sample @@ -86,6 +91,7 @@ typedef struct dds_loaned_sample { /** * @brief Generic function to increase the refcount for a loaned sample + * @ingroup loaned_sample * * @param[in] loaned_sample A loaned sample */ @@ -95,6 +101,7 @@ DDS_INLINE_EXPORT inline void ddsrt_nonnull_all dds_loaned_sample_ref (dds_loane /** * @brief Generic function to decrease the refcount for a loaned sample + * @ingroup loaned_sample * * Calls the PSMX plugin specific free function once the reference count reaches 0. * diff --git a/src/core/ddsc/include/dds/ddsc/dds_psmx.h b/src/core/ddsc/include/dds/ddsc/dds_psmx.h index bb3f401cca..2ccf4e87d9 100644 --- a/src/core/ddsc/include/dds/ddsc/dds_psmx.h +++ b/src/core/ddsc/include/dds/ddsc/dds_psmx.h @@ -11,6 +11,9 @@ /** * @defgroup psmx (Publish Subscribe Message Exchange) * @ingroup dds + * The Publish Subscribe Message Exchange (PSMX) interface allows implementing additional methods of pub-sub data-exchange + * as an alternative to Cyclone's networked transport. The PSMX interface allows to load implementations as plugins, + * so there is no need for compile-time linking. */ #ifndef DDS_PSMX_H #define DDS_PSMX_H @@ -34,6 +37,7 @@ struct dds_psmx_endpoint_list_elem; /** * @brief Type of the PSMX endpoint + * @ingroup psmx */ typedef enum dds_psmx_endpoint_type { DDS_PSMX_ENDPOINT_TYPE_UNSET, @@ -43,6 +47,7 @@ typedef enum dds_psmx_endpoint_type { /** * @brief Identifier for the PSMX instance + * @ingroup psmx */ typedef uint32_t dds_psmx_instance_id_t; @@ -55,6 +60,7 @@ typedef uint32_t dds_psmx_features_t; /** * @brief describes the data which is transferred in addition to just the sample + * @ingroup psmx */ typedef struct dds_psmx_metadata { dds_loaned_sample_state_t sample_state; @@ -70,6 +76,7 @@ typedef struct dds_psmx_metadata { /** * @brief identifier used to distinguish between PSMX instances on nodes + * @ingroup psmx */ typedef struct dds_psmx_node_identifier { @@ -78,6 +85,7 @@ typedef struct dds_psmx_node_identifier /** * @brief Definition for function that checks QoS support + * @ingroup psmx * * Definition for function that checks whether the provided QoS * is supported by the PSMX implementation. @@ -92,7 +100,7 @@ typedef bool (*dds_psmx_type_qos_supported_fn) (struct dds_psmx *psmx_instance, /** * @brief Definition for function to create a topic - * + * @ingroup psmx * Definition for a function that is called to create a new topic * for a PSMX instance. * @@ -110,7 +118,7 @@ typedef struct dds_psmx_topic * (* dds_psmx_create_topic_fn) ( /** * @brief Definition for function to destruct a topic - * + * @ingroup psmx * Definition for a function that is called on topic destruction. * * @param[in] psmx_topic The PSMX topic to destruct @@ -121,7 +129,7 @@ typedef dds_return_t (*dds_psmx_delete_topic_fn) (struct dds_psmx_topic *psmx_to /** * @brief Function definition for pubsub message exchange cleanup - * + * @ingroup psmx * @param[in] psmx_instance the psmx instance to de-initialize * @returns a DDS return code */ @@ -129,7 +137,7 @@ typedef dds_return_t (* dds_psmx_deinit_fn) (struct dds_psmx *psmx_instance); /** * @brief Definition for PSMX locator generation function - * + * @ingroup psmx * Returns a locator which is unique between nodes, but identical for instances on * the same node * @@ -140,7 +148,7 @@ typedef dds_psmx_node_identifier_t (* dds_psmx_get_node_identifier_fn) (const st /** * @brief Definition for PSMX function to get supported features - * + * @ingroup psmx * Returns an integer with the flags set for the features that are * supported by the provided PSMX instance. * @@ -152,6 +160,7 @@ typedef dds_psmx_features_t (* dds_psmx_supported_features_fn) (const struct dds /** * @brief functions which are used on a PSMX instance + * @ingroup psmx */ typedef struct dds_psmx_ops { dds_psmx_type_qos_supported_fn type_qos_supported; @@ -164,6 +173,7 @@ typedef struct dds_psmx_ops { /** * @brief Definition of function to create an endpoint for a topic + * @ingroup psmx * * @param[in] psmx_topic The PSMX topic to create the endpoint for * @param[in] endpoint_type The type of endpoint to create (publisher or subscriber) @@ -173,6 +183,7 @@ typedef struct dds_psmx_endpoint * (* dds_psmx_create_endpoint_fn) (struct dds_p /** * @brief Definition of function to delete an PSMX endpoint + * @ingroup psmx * * @param[in] psmx_endpoint The endpoint to be deleted * @returns a DDS return code @@ -181,6 +192,7 @@ typedef dds_return_t (* dds_psmx_delete_endpoint_fn) (struct dds_psmx_endpoint * /** * @brief functions which are used on a PSMX topic + * @ingroup psmx */ typedef struct dds_psmx_topic_ops { dds_psmx_create_endpoint_fn create_endpoint; @@ -190,6 +202,7 @@ typedef struct dds_psmx_topic_ops { /** * @brief Definition for function to requests a loan from the PSMX + * @ingroup psmx * * @param[in] psmx_endpoint the endpoint to loan from * @param[in] size_requested the size of the loan requested @@ -199,6 +212,7 @@ typedef dds_loaned_sample_t * (* dds_psmx_endpoint_request_loan_fn) (struct dds_ /** * @brief Definition of function to write data on a PSMX endpoint + * @ingroup psmx * * @param[in] psmx_endpoint The endpoint to publish the data on * @param[in] data The data to publish @@ -208,6 +222,7 @@ typedef dds_return_t (* dds_psmx_endpoint_write_fn) (struct dds_psmx_endpoint *p /** * @brief Definition of function to take data from an PSMX endpoint + * @ingroup psmx * * Used in a poll based implementation. * @@ -218,6 +233,7 @@ typedef dds_loaned_sample_t * (* dds_psmx_endpoint_take_fn) (struct dds_psmx_end /** * @brief Definition of function to set the a callback function on an PSMX endpoint + * @ingroup psmx * * @param[in] psmx_endpoint the endpoint to set the callback function on * @param[in] reader the DDS reader associated with the endpoint @@ -227,6 +243,7 @@ typedef dds_return_t (* dds_psmx_endpoint_on_data_available_fn) (struct dds_psmx /** * @brief Functions that are used on a PSMX endpoint + * @ingroup psmx */ typedef struct dds_psmx_endpoint_ops { dds_psmx_endpoint_request_loan_fn request_loan; @@ -237,6 +254,7 @@ typedef struct dds_psmx_endpoint_ops { /** * @brief the top-level entry point on the PSMX is bound to a specific implementation of a PSMX + * @ingroup psmx */ typedef struct dds_psmx { dds_psmx_ops_t ops; //!< associated functions @@ -249,6 +267,7 @@ typedef struct dds_psmx { /** * @brief the topic-level PSMX + * @ingroup psmx * * this will exchange data for readers and writers which are matched through discovery * will only exchange a single type of data @@ -265,6 +284,7 @@ typedef struct dds_psmx_topic { /** * @brief the definition of one instance of a dds reader/writer using a PSMX instance + * @ingroup psmx */ typedef struct dds_psmx_endpoint { dds_psmx_endpoint_ops_t ops; //!< associated functions @@ -275,6 +295,7 @@ typedef struct dds_psmx_endpoint { /** * @brief adds a topic to the list + * @ingroup psmx * * will create the first list entry if it does not yet exist * @@ -286,6 +307,7 @@ DDS_EXPORT dds_return_t dds_add_psmx_topic_to_list (struct dds_psmx_topic *psmx_ /** * @brief removes a topic from the list + * @ingroup psmx * * will set the pointer to the list to null if the last entry is removed * @@ -297,6 +319,7 @@ DDS_EXPORT dds_return_t dds_remove_psmx_topic_from_list (struct dds_psmx_topic * /** * @brief adds an endpoint to the list + * @ingroup psmx * * will create the first list entry if it does not yet exist * @@ -308,6 +331,7 @@ DDS_EXPORT dds_return_t dds_add_psmx_endpoint_to_list (struct dds_psmx_endpoint /** * @brief removes an endpoint from the list + * @ingroup psmx * * will set the pointer to the list to null if the last entry is removed * @@ -319,6 +343,7 @@ DDS_EXPORT dds_return_t dds_remove_psmx_endpoint_from_list (struct dds_psmx_endp /** * @brief initialization function for PSMX instance + * @ingroup psmx * * Should be called from all constructors of class which inherit from dds_psmx_t * @@ -329,6 +354,7 @@ DDS_EXPORT dds_return_t dds_psmx_init_generic (struct dds_psmx *psmx); /** * @brief cleanup function for a PSMX instance + * @ingroup psmx * * Should be called from all destructors of classes which inherit from dds_psmx_t * @@ -339,6 +365,7 @@ DDS_EXPORT dds_return_t dds_psmx_cleanup_generic (struct dds_psmx *psmx); /** * @brief init function for topic + * @ingroup psmx * * Should be called from all constructors of classes which inherit from struct dds_psmx_topic * @@ -354,6 +381,7 @@ DDS_EXPORT dds_return_t dds_psmx_topic_init_generic (struct dds_psmx_topic *psmx /** * @brief cleanup function for a topic + * @ingroup psmx * * Should be called from all destructors of classes which inherit from struct dds_psmx_topic * @@ -365,6 +393,7 @@ DDS_EXPORT dds_return_t dds_psmx_topic_cleanup_generic(struct dds_psmx_topic *ps /** * @brief Gets the supported features for a PSMX instance + * @ingroup psmx * * Returns the set of supported features for the provided PSMX instance. * diff --git a/src/core/ddsc/include/dds/ddsc/dds_public_dynamic_type.h b/src/core/ddsc/include/dds/ddsc/dds_public_dynamic_type.h index 94c3f670f2..5bbcd97054 100644 --- a/src/core/ddsc/include/dds/ddsc/dds_public_dynamic_type.h +++ b/src/core/ddsc/include/dds/ddsc/dds_public_dynamic_type.h @@ -316,7 +316,7 @@ DDS_EXPORT dds_dynamic_type_t dds_dynamic_type_create (dds_entity_t entity, dds_ * @component dynamic_type_api * * @param[in,out] type Dynamic Type to set the extensibility for. This can be a structure, union, bitmask or enum type. This type must be in the CONSTRUCTING state and have no members added. - * @param[in] extensibility The extensibility to set (@ref enum dds_dynamic_type_extensibility). + * @param[in] extensibility The extensibility to set (@ref dds_dynamic_type_extensibility). * * @return dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value. * diff --git a/src/core/ddsc/include/dds/ddsc/dds_public_loan_api.h b/src/core/ddsc/include/dds/ddsc/dds_public_loan_api.h index 992a2a736d..89013eca02 100644 --- a/src/core/ddsc/include/dds/ddsc/dds_public_loan_api.h +++ b/src/core/ddsc/include/dds/ddsc/dds_public_loan_api.h @@ -33,8 +33,8 @@ extern "C" { * @ingroup loan * * Borrow a sample from the entity, which currently must be a writer. This sample - * can then be returned using @ref `dds_return_loan` or can be used to publish data - * using @ref `dds_write` or @ref `dds_writedispose`. + * can then be returned using @ref dds_return_loan or can be used to publish data + * using @ref dds_write or @ref dds_writedispose. * * If the topic type has a fixed size (and so no internal pointers) and a PSMX interface is configured, * the memory will be borrowed from the PSMX implementation, which allows Cyclone to avoid copies @@ -65,13 +65,13 @@ DDS_EXPORT dds_return_t dds_request_loan (dds_entity_t entity, void **sample); * @component read_data * * Used to release middleware-owned samples returned by a read/take operation and samples - * borrowed from the writer using @ref `dds_request_loan`. + * borrowed from the writer using @ref dds_request_loan. * - * For reader loans, the @ref `dds_read` and @ref `dds_take` operations implicitly return + * For reader loans, the @ref dds_read and @ref dds_take operations implicitly return * outstanding loans referenced by the sample array passed in. Looping until no data is * returned therefore often eliminates the need for calling this function. * - * For writer loans, a @ref `dds_write` operation takes over the loan. Consequently, this + * For writer loans, a @ref dds_write operation takes over the loan. Consequently, this * function is only needed in the exceptional case where a loan is taken but ultimately * not used to publish data. * @@ -117,8 +117,8 @@ DDS_EXPORT bool dds_is_shared_memory_available (const dds_entity_t entity); * @ingroup loan * * Borrow a sample of a specified size from the entity, which currently must be a - * writer. This sample can then be returned using @ref `dds_return_loan` or can be - * used to publish data using @ref `dds_write` or @ref `dds_writedispose`. + * writer. This sample can then be returned using @ref dds_return_loan or can be + * used to publish data using @ref dds_write or @ref dds_writedispose. * * @note The function can only be used if dds_is_shared_memory_available is * true for the writer. diff --git a/src/core/ddsi/defconfig.c b/src/core/ddsi/defconfig.c index e25ff0df1c..17686b6ac6 100644 --- a/src/core/ddsi/defconfig.c +++ b/src/core/ddsi/defconfig.c @@ -107,6 +107,6 @@ void ddsi_config_init_default (struct ddsi_config *cfg) /* generated from _confgen.c[237308acd53897a34e8c643e16e05a61d73ffd65] */ /* generated from generate_rnc.c[b50e4b7ab1d04b2bc1d361a0811247c337b74934] */ /* generated from generate_md.c[789b92e422631684352909cfb8bf43f6ceb16a01] */ -/* generated from generate_rst.c[c35cdcdfc0bd4f10a801204a6cc5d540af696b6e] */ +/* generated from generate_rst.c[3c4b523fbb57c8e4a7e247379d06a8021ccc21c4] */ /* generated from generate_xsd.c[6b6818d7f17a35d56c376c04ec1410427f34c0f0] */ /* generated from generate_defconfig.c[63ca9d8ae2f1ce2e761c9d4c0510a45eb062d830] */ diff --git a/src/tools/_confgen/generate_rst.c b/src/tools/_confgen/generate_rst.c index 7d4116c17d..5e091fab29 100644 --- a/src/tools/_confgen/generate_rst.c +++ b/src/tools/_confgen/generate_rst.c @@ -82,7 +82,7 @@ static void printlink( (void)flags; (void)units; assert(elem->meta.title); - fprintf(out, "`%s`_", elem->meta.title); + fprintf(out, ":ref:`%s<%s>`", elem->name, elem->meta.title); } static void printtype( @@ -163,9 +163,8 @@ static void printelem( struct cfgelem *ce = firstelem(elem->attributes); while (ce) { if (!isnop(ce)) { - fprintf(out, "%s[%s](", sep, name(ce)); + fputs(sep, out); printlink(out, level, flags, ce, units); - fprintf(out, ")"); sep = ", "; cnt++; }