Documentation for transport priority feature (#1099)

* Refs #23432. Update `TransportPriorityQosPolicy` section in `Standard QoS Policies` page.

Signed-off-by: Miguel Company <miguelcompany@eprosima.com>

* Refs #23432. Fix tabs in XMLTester.xml.

Signed-off-by: Miguel Company <miguelcompany@eprosima.com>

* Refs #23432. Add configuration example.

Signed-off-by: Miguel Company <miguelcompany@eprosima.com>

* Refs #23432. Add transport_priority to profiles and full xml examples.

Signed-off-by: Miguel Company <miguelcompany@eprosima.com>

* Refs #23432. Apply review suggestions.

Signed-off-by: Miguel Company <miguelcompany@eprosima.com>

* Refs #23432. Move XML for transport_priority inside qos tag.

Signed-off-by: Miguel Company <miguelcompany@eprosima.com>

---------

Signed-off-by: Miguel Company <miguelcompany@eprosima.com>

Author: MiguelCompany

code/DDSCodeTester.cpp

@@ -4427,6 +4427,23 @@ void dds_qos_examples()
         //!--
     }
 
+    {
+        //DDS_CHANGE_TRANSPORT_PRIORITY_QOS_POLICY
+        // This example only applies to DataWriter entities
+        DataWriterQos writer_qos;
+        // The TransportPriorityQosPolicy is constructed with value 0 by default
+        // Change the value to 12
+        writer_qos.transport_priority().value = 12;
+        // Use modified QoS in the creation of the corresponding DataWriter
+        writer_ = publisher_->create_datawriter(topic_, writer_qos);
+
+        // Change the TransportPriorityQosPolicy at runtime
+        writer_qos.transport_priority().value = 23;
+        // Update the QoS in the corresponding entity
+        writer_->set_qos(writer_qos);
+        //!--
+    }
+
     {
         //DDS_CHANGE_PARTITION_QOS_POLICY
         // This example uses a Publisher, but it can also be applied to Subscriber entities

code/XMLTester.xml

@@ -72,7 +72,7 @@
             <lease_duration>
                 <sec>1</sec>
             </lease_duration>
-	    <kind>AUTOMATIC</kind>
+            <kind>AUTOMATIC</kind>
         </liveliness>
     </qos>
 </data_reader>
@@ -82,15 +82,15 @@
 <data_writer profile_name="writer_xml_conf_ownership_profile">
     <qos>
       <ownership>
-	    <kind>EXCLUSIVE</kind>
+        <kind>EXCLUSIVE</kind>
       </ownership>
     </qos>
 </data_writer>
 
 <data_reader profile_name="reader_xml_conf_ownership_profile">
     <qos>
         <ownership>
-	    <kind>EXCLUSIVE</kind>
+            <kind>EXCLUSIVE</kind>
         </ownership>
     </qos>
 </data_reader>
@@ -100,12 +100,20 @@
 <data_writer profile_name="writer_xml_conf_ownership_strength_profile">
     <qos>
         <ownershipStrength>
-	    <value>10</value>
+            <value>10</value>
         </ownershipStrength>
     </qos>
 </data_writer>
 <!--><-->
 
+<!-->PUBSUB_API_CONF_PUBSUB_TRANSPORT_PRIORITY<-->
+<data_writer profile_name="writer_xml_conf_transport_priority_profile">
+    <qos>
+        <transport_priority>12</transport_priority>
+    </qos>
+</data_writer>
+<!--><-->
+
 <!-->CONF-QOS-DATASHARING<-->
 <!--
 <?xml version="1.0" encoding="UTF-8" ?>
@@ -2079,6 +2087,8 @@
         <value>50</value>
     </ownershipStrength>
 
+    <transport_priority>12</transport_priority>
+
     <partition>
         <names>
             <name>part1</name>

code/XMLTesterExample.xml

@@ -572,6 +572,7 @@
                 <ownershipStrength>
                     <value>50</value>
                 </ownershipStrength>
+                <transport_priority>-20</transport_priority>
                 <partition>
                     <names>
                         <name>part1</name>

docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst

@@ -1296,9 +1296,6 @@ Example
 TransportPriorityQosPolicy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. warning::
-    This QoS Policy will be implemented in future releases.
-
 The purpose of this QoS Policy is to allow the service to take advantage of those transports capable of sending
 messages with different priorities. It establishes the priority of the underlying transport used to send the data.
 See |TransportPriorityQosPolicy-api|
@@ -1310,14 +1307,30 @@ List of QoS Policy data members:
 +-------------------------------------------------------------------------------------+----------------+---------------+
 | Data Member Name                                                                    | Type           | Default Value |
 +=====================================================================================+================+===============+
-| |TransportPriorityQosPolicy::value-api|                                             | ``uint32_t``   | 0             |
+| |TransportPriorityQosPolicy::value-api|                                             | ``int32_t``    | 0             |
 +-------------------------------------------------------------------------------------+----------------+---------------+
 
 .. note::
      This QoS Policy applies to |Topic| and |DataWriter| entities.
      :raw-html:`<br />`
      It can be changed on enabled entities.
 
+Example
+"""""""
+
+.. tab-set-code::
+
+    .. literalinclude:: /../code/DDSCodeTester.cpp
+        :language: c++
+        :dedent: 8
+        :start-after: //DDS_CHANGE_TRANSPORT_PRIORITY_QOS_POLICY
+        :end-before: //!
+
+    .. literalinclude:: /../code/XMLTester.xml
+        :language: xml
+        :start-after: <!-->PUBSUB_API_CONF_PUBSUB_TRANSPORT_PRIORITY
+        :end-before: <!--><-->
+
 
 .. _userdataqospolicy:
 

docs/fastdds/xml_configuration/common.rst

@@ -460,6 +460,9 @@ Please refer to the :ref:`dds_layer_core_policy` section for more information on
   * - ``<ownershipStrength>``
     - See :ref:`ownershipstrengthqospolicy`.
     - :ref:`xml_ownershipstrength`
+  * - ``<transport_priority>``
+    - See :ref:`transportpriorityqospolicy`.
+    - ``int32_t`` (default: 0)
   * - ``<partition>``
     - See :ref:`partitionqospolicy`.
     - :ref:`xml_partition`

docs/fastdds/xml_configuration/datawriter.rst

@@ -55,7 +55,7 @@ The DataWriter configuration is performed through the XML elements listed in the
      - :ref:`CommonQOS`
      -
    * - ``<times>``
-     - It configures some time related parameters  of the DataWriter.
+     - It configures some time related parameters of the DataWriter.
      - :ref:`WriterTimes <pubtimes>`
      -
    * - ``<unicastLocatorList>``