[21051] Documentation to serialize DynamicTypes to IDL

code/DDSCodeTester.cpp

@@ -5606,6 +5606,126 @@ void dynamictypes_examples()
         data->return_loaned_value(loan_data);
         //!--
     }
+    {
+        //!--CPP_HELLO_WORLD
+        // Create struct type
+        TypeDescriptor::_ref_type struct_type_descriptor {traits<TypeDescriptor>::make_shared()};
+        struct_type_descriptor->kind(TK_STRUCTURE);
+        struct_type_descriptor->name("HelloWorld");
+        DynamicTypeBuilder::_ref_type struct_builder {DynamicTypeBuilderFactory::get_instance()->
+                                                            create_type(struct_type_descriptor)};
+
+        // The type consists of two members, and index and a message. Add members to the struct.
+        MemberDescriptor::_ref_type index_member_descriptor {traits<MemberDescriptor>::make_shared()};
+        index_member_descriptor->name("index");
+        index_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->
+                        get_primitive_type(TK_UINT32));
+        struct_builder->add_member(index_member_descriptor);
+
+        MemberDescriptor::_ref_type message_member_descriptor {traits<MemberDescriptor>::make_shared()};
+        message_member_descriptor->name("message");
+        message_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->
+                        create_string_type(static_cast<uint32_t>(LENGTH_UNLIMITED))->build());
+        struct_builder->add_member(message_member_descriptor);
+
+        // Build the type
+        DynamicType::_ref_type struct_type {struct_builder->build()};
+        //!--
+    }
+    {
+        //!--CPP_BITMASK_DEFAULT_ANNOTATIONS
+        // Define a struct type to contain a bitmask
+        TypeDescriptor::_ref_type type_descriptor {traits<TypeDescriptor>::make_shared()};
+        type_descriptor->kind(TK_STRUCTURE);
+        type_descriptor->name("BitmaskStruct");
+        DynamicTypeBuilder::_ref_type struct_builder {DynamicTypeBuilderFactory::get_instance()->
+                                                              create_type(type_descriptor)};
+
+        // Define the bitmask type
+        DynamicTypeBuilder::_ref_type bitmask_builder {DynamicTypeBuilderFactory::get_instance()->create_bitmask_type(32)};
+
+        /* Alternative
+            TypeDescriptor::_ref_type bitmask_type_descriptor {traits<TypeDescriptor>::make_shared()};
+            bitmask_type_descriptor->kind(TK_BITMASK);
+            bitmask_type_descriptor->name("MyBitMask");
+            bitmask_type_descriptor->element_type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(
+                        TK_BOOLEAN));
+            bitmask_type_descriptor->bound().push_back(32);
+            DynamicTypeBuilder::_ref_type bitmask_builder {DynamicTypeBuilderFactory::get_instance()->create_type(
+                                                            bitmask_type_descriptor)};
+        */
+
+        // Add bitfield members to the bitmask type
+        MemberDescriptor::_ref_type bitfield_member_descriptor {traits<MemberDescriptor>::make_shared()};
+        bitfield_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_BOOLEAN));
+        bitfield_member_descriptor->name("flag0");
+        bitfield_member_descriptor->id(0);
+        bitmask_builder->add_member(bitfield_member_descriptor);
+        bitfield_member_descriptor = traits<MemberDescriptor>::make_shared();
+        bitfield_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_BOOLEAN));
+        bitfield_member_descriptor->name("flag1");
+        bitfield_member_descriptor->id(2);
+        bitmask_builder->add_member(bitfield_member_descriptor);
+        bitfield_member_descriptor = traits<MemberDescriptor>::make_shared();
+        bitfield_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_BOOLEAN));
+        bitfield_member_descriptor->name("flag2");
+        bitmask_builder->add_member(bitfield_member_descriptor);
+        // Build the bitmask type
+        DynamicType::_ref_type bitmask_type =  bitmask_builder->build();
+
+        // Add a bitmask member to the struct
+        MemberDescriptor::_ref_type member_descriptor {traits<MemberDescriptor>::make_shared()};
+        member_descriptor->name("my_bitmask");
+        member_descriptor->type(bitmask_type);
+        struct_builder->add_member(member_descriptor);
+        // Build the struct type
+        DynamicType::_ref_type struct_type {struct_builder->build()};
+        //!--
+    }
+    {
+        //!--CPP_BITSET_DEFAULT_TYPES
+        // Define a struct type to contain the bitset
+        TypeDescriptor::_ref_type struct_type_descriptor {traits<TypeDescriptor>::make_shared()};
+        struct_type_descriptor->kind(TK_STRUCTURE);
+        struct_type_descriptor->name("BitsetStruct");
+        DynamicTypeBuilder::_ref_type struct_builder {DynamicTypeBuilderFactory::get_instance()->create_type(
+                                                          struct_type_descriptor)};
+
+        // Define type for my_bitset
+        TypeDescriptor::_ref_type bitset_type_descriptor {traits<TypeDescriptor>::make_shared()};
+        bitset_type_descriptor->kind(TK_BITSET);
+        bitset_type_descriptor->name("MyBitSet");
+        bitset_type_descriptor->bound({3, 1, 12});
+        DynamicTypeBuilder::_ref_type bitset_builder {DynamicTypeBuilderFactory::get_instance()->create_type(
+                                                          bitset_type_descriptor)};
+        // Add members to the bitset type
+        MemberDescriptor::_ref_type bitset_member_descriptor {traits<MemberDescriptor>::make_shared()};
+        bitset_member_descriptor->name("a");
+        bitset_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_UINT8));
+        bitset_member_descriptor->id(0);
+        bitset_builder->add_member(bitset_member_descriptor);
+        bitset_member_descriptor = traits<MemberDescriptor>::make_shared();
+        bitset_member_descriptor->name("b");
+        bitset_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_BOOLEAN));
+        bitset_member_descriptor->id(3);
+        bitset_builder->add_member(bitset_member_descriptor);
+        bitset_member_descriptor = traits<MemberDescriptor>::make_shared();
+        bitset_member_descriptor->name("c");
+        bitset_member_descriptor->type(DynamicTypeBuilderFactory::get_instance()->get_primitive_type(TK_INT16));
+        bitset_member_descriptor->id(4);
+        bitset_builder->add_member(bitset_member_descriptor);
+        // Build the bitset type
+        DynamicType::_ref_type bitset_type = bitset_builder->build();
+
+        // Add the bitset member to the struct
+        MemberDescriptor::_ref_type member_descriptor {traits<MemberDescriptor>::make_shared()};
+        member_descriptor->name("my_bitset");
+        member_descriptor->type(bitset_type);
+        struct_builder->add_member(member_descriptor);
+        // Build the struct type
+        DynamicType::_ref_type struct_type {struct_builder->build()};
+        //!--
+    }
 }
 
 void xml_profiles_examples()

code/DynamicTypesIDLExamples.idl

@@ -202,3 +202,39 @@ struct AnnotatedStruct
     @MyAnnotation(length = 10) string string_var;
 };
 //!--
+
+//!--IDL_HELLO_WORLD
+struct HelloWorld
+{
+    unsigned long index;
+    string message;
+};
+//!--
+
+//!--IDL_BITMASK_DEFAULT_ANNOTATIONS
+bitmask MyBitMask
+{
+    flag0,
+    @position(2) flag1,
+    flag2
+};
+
+struct BitmaskStruct
+{
+    MyBitMask my_bitmask;
+};
+//!--
+
+//!--IDL_BITSET_DEFAULT_TYPES
+bitset MyBitSet
+{
+    bitfield<3> a;
+    bitfield<1> b;
+    bitfield<12, short> c;
+};
+
+struct BitsetStruct
+{
+   MyBitSet my_bitset;
+};
+//!--

code/XMLTester.xml

@@ -4570,6 +4570,37 @@
 <!-- XML Types Profiles does not support defining/setting custom annotations -->
 <!--><-->
 
+<!-->XML_HELLO_WORLD<-->
+<struct name="HelloWorld">
+    <member name="index" type="uint32"/>
+    <member name="message" type="string"/>
+</struct>
+<!--><-->
+
+<!-->XML_BITMASK_DEFAULT_ANNOTATIONS<-->
+<bitmask name="MyBitMask" bit_bound="32">
+    <bit_value name="flag0" position="0"/>
+    <bit_value name="flag1" position="2"/>
+    <bit_value name="flag2"/>
+</bitmask>
+
+<struct name="BitmaskStruct">
+    <member name="my_bitmask" type="nonBasic" nonBasicTypeName="MyBitMask"/>
+</struct>
+<!--><-->
+
+<!-->XML_BITSET_DEFAULT_TYPES<-->
+<bitset name="MyBitset">
+    <bitfield name="a" bit_bound="3" type="uint8" />
+    <bitfield name="b" bit_bound="1" type="bool" />
+    <bitfield name="c" bit_bound="12" type="int16"/>
+</bitset>
+
+<struct name="BitsetStruct">
+    <member name="my_bitset" type="nonBasic" nonBasicTypeName="MyBitSet"/>
+</struct>
+<!--><-->
+
 </type>
 </types>
 </dds>

docs/fastdds/xtypes/language_binding.rst

@@ -836,6 +836,8 @@ modifies the involved bits instead of the full primitive value.
 For a detailed explanation about the XML definition of this type, please refer to
 :ref:`XML Bitset Types<xmldynamictypes_bitset>`.
 
+.. _xtypes_annotations:
+
 Annotations
 ^^^^^^^^^^^
 

docs/fastdds/xtypes/type_serializing.rst

@@ -0,0 +1,110 @@
+.. include:: ../../03-exports/aliases-api.include
+
+.. _xtypes_type_serializing:
+
+Dynamic Type Serializing
+========================
+
+Fast-DDS provides methods to serialize `DynamicType` objects.
+
+Dynamic Type to IDL
+-------------------
+
+The method `idl_serialize` converts a `DynamicType` object into an IDL string.
+The following `DynamicType` object would be serialized as follows:
+
+.. tabs::
+
+    .. tab:: IDL
+
+        .. literalinclude:: /../code/DynamicTypesIDLExamples.idl
+            :language: omg-idl
+            :start-after: //!--IDL_HELLO_WORLD
+            :end-before: //!--
+
+    .. tab:: XML
+
+        .. literalinclude:: /../code/XMLTester.xml
+            :language: xml
+            :start-after: <!-->XML_HELLO_WORLD<-->
+            :end-before: <!--><-->
+
+    .. tab:: C++
+
+        .. literalinclude:: /../code/DDSCodeTester.cpp
+            :language: c++
+            :start-after: //!--CPP_HELLO_WORLD
+            :end-before: //!--
+
+.. note::
+
+    The conversion to IDL only supports the annotations: `@bit_bound`, `@extensibility`, `@key`, and `@position`.
+
+.. note::
+
+    The conversion to IDL supports inheritance of :ref:`xtypes_supportedtypes_struct` fully, and of :ref:`xtypes_supportedtypes_bitset` at the cost of collapsing the base and derived bitsets into a single bitset.
+
+Default values
+++++++++++++++
+
+In general, if a user explicitly sets a value to its default value, the serialization to IDL will not set the value explicitly.
+
+Example: annotations
+^^^^^^^^^^^^^^^^^^^^
+
+In the following example, `MyBitMask` has two explicit annotations (`@bit_bound(32)` and `@position(0)`) that do not appear in the IDL, since they both are the default values.
+The annotation `@position(2)` does appear, since it is not the default.
+Furthermore, the annotation `@position(2)` increases the position of `flag2` to `3`, but the `@position(3)` annotation does not appear since by default the position is one more than the previous position.
+
+.. tabs::
+
+    .. tab:: IDL
+
+        .. literalinclude:: /../code/DynamicTypesIDLExamples.idl
+            :language: omg-idl
+            :start-after: //!--IDL_BITMASK_DEFAULT_ANNOTATIONS
+            :end-before: //!--
+
+    .. tab:: XML
+
+        .. literalinclude:: /../code/XMLTester.xml
+            :language: xml
+            :start-after: <!-->XML_BITMASK_DEFAULT_ANNOTATIONS<-->
+            :end-before: <!--><-->
+
+    .. tab:: C++
+
+        .. literalinclude:: /../code/DDSCodeTester.cpp
+            :language: c++
+            :start-after: //!--CPP_BITMASK_DEFAULT_ANNOTATIONS
+            :end-before: //!--
+
+Example: bitsets
+^^^^^^^^^^^^^^^^
+
+In the following example, the three bitfields of `MyBitSet` explicitly specify their type.
+Two of the types (`unsigned char` and `boolean`) are the default and, therefore, do not appear in the IDL.
+The type `short` does appear since it is not the default type for a 12-bit long variable.
+
+.. tabs::
+
+    .. tab:: IDL
+
+        .. literalinclude:: /../code/DynamicTypesIDLExamples.idl
+            :language: omg-idl
+            :start-after: //!--IDL_BITSET_DEFAULT_TYPES
+            :end-before: //!--
+
+    .. tab:: XML
+
+        .. literalinclude:: /../code/XMLTester.xml
+            :language: xml
+            :start-after: <!-->XML_BITSET_DEFAULT_TYPES<-->
+            :end-before: <!--><-->
+
+    .. tab:: C++
+
+        .. literalinclude:: /../code/DDSCodeTester.cpp
+            :language: c++
+            :start-after: //!--CPP_BITSET_DEFAULT_TYPES
+            :end-before: //!--

docs/fastdds/xtypes/xtypes.rst

@@ -23,6 +23,7 @@ This specification defines the following concepts:
 
    /fastdds/xtypes/discovery_matching.rst
    /fastdds/xtypes/language_binding.rst
+   /fastdds/xtypes/type_serializing.rst
 
 .. note::