docs: improve generated `libqmi-glib' documentation

Among the tons of fixes done here, we now generate some per-service .sections
file which we then concatenate to build the final libqmi-glib-sections.txt file.

14 files changed, 396 insertions, 15 deletions

diff --git a/build-aux/qmi-codegen/Client.py b/build-aux/qmi-codegen/Client.py
index 9bab465..f2f92ee 100644
--- a/build-aux/qmi-codegen/Client.py
+++ b/build-aux/qmi-codegen/Client.py
@@ -34,11 +34,14 @@ class Client:
     """
     def __init__(self, objects_dictionary):
         self.name = None
+        self.service = None
 
         # Loop items in the list, looking for the special 'Client' type
         for object_dictionary in objects_dictionary:
             if object_dictionary['type'] == 'Client':
                 self.name = object_dictionary['name']
+            elif object_dictionary['type'] == 'Service':
+                self.service = object_dictionary['name']
 
         # We NEED the Client field
         if self.name is None:
@@ -59,7 +62,9 @@ class Client:
 
         translations = { 'underscore'                 : utils.build_underscore_name(self.name),
                          'no_prefix_underscore_upper' : string.upper(utils.build_underscore_name(self.name[4:])),
-                         'camelcase'                  : utils.build_camelcase_name (self.name) }
+                         'camelcase'                  : utils.build_camelcase_name(self.name),
+                         'hyphened'                   : utils.build_dashed_name(self.name),
+                         'service'                    : string.upper(self.service) }
 
         # Emit class header
         template = (
@@ -73,12 +78,20 @@ class Client:
             'typedef struct _${camelcase} ${camelcase};\n'
             'typedef struct _${camelcase}Class ${camelcase}Class;\n'
             '\n'
+            '/**\n'
+            ' * ${camelcase}:\n'
+            ' *\n'
+            ' * The #${camelcase} structure contains private data and should only be accessed\n'
+            ' * using the provided API.\n'
+            ' */\n'
             'struct _${camelcase} {\n'
+            '    /*< private >*/\n'
             '    QmiClient parent;\n'
             '    gpointer priv_unused;\n'
             '};\n'
             '\n'
             'struct _${camelcase}Class {\n'
+            '    /*< private >*/\n'
             '    QmiClientClass parent;\n'
             '};\n'
             '\n'
@@ -89,6 +102,14 @@ class Client:
         # Emit class source
         template = (
             '\n'
+            '/**\n'
+            ' * SECTION: ${hyphened}\n'
+            ' * @title: ${camelcase}\n'
+            ' * @short_description: #QmiClient for the ${service} service.\n'
+            ' *\n'
+            ' * #QmiClient which handles operations in the ${service} service.\n'
+            ' */\n'
+            '\n'
             'G_DEFINE_TYPE (${camelcase}, ${underscore}, QMI_TYPE_CLIENT);\n')
 
         if has_indications:
@@ -177,11 +198,14 @@ class Client:
             if message.type == 'Indication':
                 translations['signal_name'] = utils.build_dashed_name(message.name)
                 translations['signal_id'] = utils.build_underscore_uppercase_name(message.name)
+                translations['message_name'] = message.name
                 inner_template = ''
                 if message.output is not None and message.output.fields is not None:
                     # At least one field in the indication
                     translations['output_camelcase'] = utils.build_camelcase_name(message.output.fullname)
                     translations['bundle_type'] = 'QMI_TYPE_' + utils.remove_prefix(utils.build_underscore_uppercase_name(message.output.fullname), 'QMI_')
+                    translations['service'] = string.upper(self.service)
+                    translations['message_name_dashed'] = string.replace(message.name, ' ', '-')
                     inner_template += (
                         '\n'
                         '    /**\n'
@@ -189,7 +213,7 @@ class Client:
                         '     * @object: A #${camelcase}.\n'
                         '     * @output: A #${output_camelcase}.\n'
                         '     *\n'
-                        '     * The ::${signal_name} signal gets emitted when a \'${message_name}\' indication is received.\n'
+                        '     * The ::${signal_name} signal gets emitted when a \'<link linkend=\"libqmi-glib-${service}-${message_name_dashed}.top_of_page\">${message_name}</link>\' indication is received.\n'
                         '     */\n'
                         '    signals[SIGNAL_${signal_id}] =\n'
                         '        g_signal_new ("${signal_name}",\n'
@@ -242,6 +266,7 @@ class Client:
             if message.type == 'Indication':
                 continue
 
+            translations['message_name'] = message.name
             translations['message_underscore'] = utils.build_underscore_name(message.name)
             translations['message_fullname_underscore'] = utils.build_underscore_name(message.fullname)
             translations['input_camelcase'] = utils.build_camelcase_name(message.input.fullname)
@@ -252,9 +277,11 @@ class Client:
             if message.input.fields is None:
                 input_arg_template = 'gpointer unused'
                 translations['input_var'] = 'NULL'
+                translations['input_doc'] = 'unused: %NULL. This message doesn\'t have any input bundle.'
             else:
                 input_arg_template = '${input_camelcase} *input'
                 translations['input_var'] = 'input'
+                translations['input_doc'] = 'input: a #' + translations['input_camelcase'] + '.'
             template = (
                 '\n'
                 'void ${underscore}_${message_underscore} (\n'
@@ -272,6 +299,16 @@ class Client:
 
             template = (
                 '\n'
+                '/**\n'
+                ' * ${underscore}_${message_underscore}_finish:\n'
+                ' * @self: a #${camelcase}.\n'
+                ' * @res: the #GAsyncResult obtained from the #GAsyncReadyCallback passed to ${underscore}_${message_underscore}().\n'
+                ' * @error: Return location for error or %%NULL.\n'
+                ' *\n'
+                ' * Finishes an async operation started with ${underscore}_${message_underscore}().\n'
+                ' *\n'
+                ' * Returns: a #${output_camelcase}, or %%NULL if @error is set. The returned value should be freed with ${output_underscore}_unref().\n'
+                ' */\n'
                 '${output_camelcase} *\n'
                 '${underscore}_${message_underscore}_finish (\n'
                 '    ${camelcase} *self,\n'
@@ -315,6 +352,21 @@ class Client:
                 '    qmi_message_unref (reply);\n'
                 '}\n'
                 '\n'
+                '/**\n'
+                ' * ${underscore}_${message_underscore}:\n'
+                ' * @self: a #${camelcase}.\n'
+                ' * @${input_doc}\n'
+                ' * @timeout: maximum time to wait for the method to complete, in seconds.\n'
+                ' * @cancellable: a #GCancellable or %%NULL.\n'
+                ' * @callback: a #GAsyncReadyCallback to call when the request is satisfied.\n'
+                ' * @user_data: user data to pass to @callback.\n'
+                ' *\n'
+                ' * Asynchronously sends a ${message_name} request to the device.\n'
+                ' *\n'
+                ' * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from.\n'
+                ' *\n'
+                ' * You can then call ${underscore}_${message_underscore}_finish() to get the result of the operation.\n'
+                ' */\n'
                 'void\n'
                 '${underscore}_${message_underscore} (\n'
                 '    ${camelcase} *self,\n'
@@ -367,3 +419,31 @@ class Client:
         utils.add_separator(cfile, 'CLIENT', self.name);
         self.__emit_class(hfile, cfile, message_list)
         self.__emit_methods(hfile, cfile, message_list)
+
+
+    """
+    Emit the sections
+    """
+    def emit_sections(self, sfile):
+        translations = { 'underscore'                 : utils.build_underscore_name(self.name),
+                         'no_prefix_underscore_upper' : string.upper(utils.build_underscore_name(self.name[4:])),
+                         'camelcase'                  : utils.build_camelcase_name (self.name),
+                         'hyphened'                   : utils.build_dashed_name (self.name) }
+
+        template = (
+            '<SECTION>\n'
+            '<FILE>${hyphened}</FILE>\n'
+            '<TITLE>${camelcase}</TITLE>\n'
+            '${camelcase}\n'
+            '<SUBSECTION Standard>\n'
+            '${camelcase}Class\n'
+            'QMI_TYPE_${no_prefix_underscore_upper}\n'
+            'QMI_${no_prefix_underscore_upper}\n'
+            'QMI_${no_prefix_underscore_upper}_CLASS\n'
+            'QMI_IS_${no_prefix_underscore_upper}\n'
+            'QMI_IS_${no_prefix_underscore_upper}_CLASS\n'
+            'QMI_${no_prefix_underscore_upper}_GET_CLASS\n'
+            '${underscore}_get_type\n'
+            '</SECTION>\n'
+            '\n')
+        sfile.write(string.Template(template).substitute(translations))
diff --git a/build-aux/qmi-codegen/Container.py b/build-aux/qmi-codegen/Container.py
index 8342beb..f15e6b1 100644
--- a/build-aux/qmi-codegen/Container.py
+++ b/build-aux/qmi-codegen/Container.py
@@ -117,9 +117,15 @@ class Container:
         # Emit types header
         template = (
             '\n'
+            '/**\n'
+            ' * ${camelcase}:\n'
+            ' *\n'
+            ' * The #${camelcase} structure contains private data and should only be accessed\n'
+            ' * using the provided API.\n'
+            ' */\n'
+            'typedef struct _${camelcase} ${camelcase};\n'
             'GType ${underscore}_get_type (void) G_GNUC_CONST;\n'
-            '#define ${type_macro} (${underscore}_get_type ())\n'
-            'typedef struct _${camelcase} ${camelcase};\n')
+            '#define ${type_macro} (${underscore}_get_type ())\n')
         hfile.write(string.Template(template).substitute(translations))
 
         # Emit types source
@@ -281,3 +287,40 @@ class Container:
 
         # Emit the container core
         self.__emit_core(hfile, cfile, translations)
+
+
+    """
+    Add sections
+    """
+    def add_sections(self, sections):
+        if self.fields is None:
+            return
+
+        translations = { 'name'       : self.name,
+                         'camelcase'  : utils.build_camelcase_name (self.fullname),
+                         'underscore' : utils.build_underscore_name (self.fullname),
+                         'type_macro' : 'QMI_TYPE_' + utils.remove_prefix(utils.build_underscore_uppercase_name(self.fullname), 'QMI_') }
+
+        # Standard
+        template = (
+            '${underscore}_get_type\n'
+            '${type_macro}\n')
+        sections['standard'] += string.Template(template).substitute(translations)
+
+        # Public types
+        template = (
+            '${camelcase}\n')
+        sections['public-types'] += string.Template(template).substitute(translations)
+
+        # Public methods
+        template = '<SUBSECTION ${camelcase}Methods>\n'
+        if self.readonly == False:
+            template += (
+                '${underscore}_new\n')
+        template += (
+            '${underscore}_ref\n'
+            '${underscore}_unref\n')
+        sections['public-methods'] += string.Template(template).substitute(translations)
+
+        for field in self.fields:
+            field.add_sections(sections)
diff --git a/build-aux/qmi-codegen/Field.py b/build-aux/qmi-codegen/Field.py
index 19657ff..1faff41 100644
--- a/build-aux/qmi-codegen/Field.py
+++ b/build-aux/qmi-codegen/Field.py
@@ -123,11 +123,11 @@ class Field:
             ' * ${prefix_underscore}_get_${underscore}:\n'
             ' * @self: a #${prefix_camelcase}.\n'
             '${variable_getter_doc}'
-            ' * @error: a #GError.\n'
+            ' * @error: Return location for error or %NULL.\n'
             ' *\n'
             ' * Get the \'${name}\' field from @self.\n'
             ' *\n'
-            ' * Returns: #TRUE if the field is found, #FALSE otherwise.\n'
+            ' * Returns: %TRUE if the field is found, %FALSE otherwise.\n'
             ' */\n'
             'gboolean\n'
             '${prefix_underscore}_get_${underscore} (\n'
@@ -186,11 +186,11 @@ class Field:
             ' * ${prefix_underscore}_set_${underscore}:\n'
             ' * @self: a #${prefix_camelcase}.\n'
             '${variable_setter_doc}'
-            ' * @error: a #GError.\n'
+            ' * @error: Return location for error or %NULL.\n'
             ' *\n'
             ' * Set the \'${name}\' field in the message.\n'
             ' *\n'
-            ' * Returns: #TRUE if @value was successfully set, #FALSE otherwise.\n'
+            ' * Returns: %TRUE if @value was successfully set, %FALSE otherwise.\n'
             ' */\n'
             'gboolean\n'
             '${prefix_underscore}_set_${underscore} (\n'
@@ -357,3 +357,24 @@ class Field:
             '    return NULL;\n'
             '}\n')
         f.write(string.Template(template).substitute(translations))
+
+
+    """
+    Add sections
+    """
+    def add_sections(self, sections):
+        translations = { 'underscore'        : utils.build_underscore_name(self.name),
+                         'prefix_camelcase'  : utils.build_camelcase_name(self.prefix),
+                         'prefix_underscore' : utils.build_underscore_name(self.prefix) }
+
+        if TypeFactory.is_section_emitted(self.fullname) is False:
+            TypeFactory.set_section_emitted(self.fullname)
+            self.variable.add_sections(sections)
+
+        # Public methods
+        template = (
+            '${prefix_underscore}_get_${underscore}\n')
+        if self.container_type == 'Input':
+            template += (
+                '${prefix_underscore}_set_${underscore}\n')
+        sections['public-methods'] += string.Template(template).substitute(translations)
diff --git a/build-aux/qmi-codegen/FieldResult.py b/build-aux/qmi-codegen/FieldResult.py
index fb8d521..c249492 100644
--- a/build-aux/qmi-codegen/FieldResult.py
+++ b/build-aux/qmi-codegen/FieldResult.py
@@ -64,11 +64,11 @@ class FieldResult(Field):
             '/**\n'
             ' * ${prefix_underscore}_get_result:\n'
             ' * @self: a ${prefix_camelcase}.\n'
-            ' * @error: a #GError.\n'
+            ' * @error: Return location for error or %NULL.\n'
             ' *\n'
             ' * Get the result of the QMI operation.\n'
             ' *\n'
-            ' * Returns: #TRUE if the QMI operation succeeded, #FALSE if @error is set.\n'
+            ' * Returns: %TRUE if the QMI operation succeeded, %FALSE if @error is set.\n'
             ' */\n'
             'gboolean\n'
             '${prefix_underscore}_get_result (\n'
@@ -159,3 +159,20 @@ class FieldResult(Field):
             '    return NULL;\n'
             '}\n')
         f.write(string.Template(template).substitute(translations))
+
+
+    """
+    Add sections
+    """
+    def add_sections(self, sections):
+        translations = { 'underscore'        : utils.build_underscore_name(self.name),
+                         'prefix_camelcase'  : utils.build_camelcase_name(self.prefix),
+                         'prefix_underscore' : utils.build_underscore_name(self.prefix) }
+
+        # Public methods
+        template = (
+            '${prefix_underscore}_get_${underscore}\n')
+        if self.container_type == 'Input':
+            template += (
+                '${prefix_underscore}_set_${underscore}\n')
+        sections['public-methods'] += string.Template(template).substitute(translations)
diff --git a/build-aux/qmi-codegen/Message.py b/build-aux/qmi-codegen/Message.py
index 08d0b36..25e6adb 100644
--- a/build-aux/qmi-codegen/Message.py
+++ b/build-aux/qmi-codegen/Message.py
@@ -206,7 +206,7 @@ class Message:
             '/**\n'
             ' * ${underscore}_${type}_parse:\n'
             ' * @message: a #QmiMessage ${type}.\n'
-            ' * @error: a #GError.\n'
+            ' * @error: Return location for error or %%NULL.\n'
             ' *\n'
             ' * Parse the \'${name}\' ${type}.\n'
             ' *\n'
@@ -424,3 +424,60 @@ class Message:
         hfile.write('\n/* --- Printable -- */\n');
         cfile.write('\n/* --- Printable -- */\n');
         self.__emit_get_printable(hfile, cfile)
+
+    """
+    Emit the sections
+    """
+    def emit_sections(self, sfile):
+
+        translations = { 'hyphened'            : utils.build_dashed_name (self.fullname),
+                         'fullname_underscore' : utils.build_underscore_name(self.fullname),
+                         'camelcase'           : utils.build_camelcase_name (self.fullname),
+                         'service'             : utils.build_underscore_name (self.service),
+                         'name_underscore'     : utils.build_underscore_name (self.name),
+                         'fullname'            : self.service + ' ' + self.name,
+                         'type'                : 'response' if self.type == 'Message' else 'indication' }
+
+        sections = { 'public-types'   : '',
+                     'public-methods' : '',
+                     'standard'       : '',
+                     'private'        : '' }
+
+        if self.input:
+            self.input.add_sections (sections)
+        self.output.add_sections (sections)
+
+        if self.type == 'Message':
+            template = (
+                '<SUBSECTION ${camelcase}ClientMethods>\n'
+                'qmi_client_${service}_${name_underscore}\n'
+                'qmi_client_${service}_${name_underscore}_finish\n')
+            sections['public-methods'] += string.Template(template).substitute(translations)
+
+        translations['public_types']   = sections['public-types']
+        translations['public_methods'] = sections['public-methods']
+        translations['standard']       = sections['standard']
+        translations['private']        = sections['private']
+
+        template = (
+            '<SECTION>\n'
+            '<FILE>${hyphened}</FILE>\n'
+            '<TITLE>${fullname}</TITLE>\n'
+            '${public_types}'
+            '${public_methods}'
+            '<SUBSECTION Private>\n'
+            '${private}')
+
+        if self.input:
+            template += '${fullname_underscore}_request_create\n'
+
+        if self.output.fields is not None:
+            template += (
+                '${fullname_underscore}_${type}_parse\n')
+
+        template += (
+            '<SUBSECTION Standard>\n'
+            '${standard}'
+            '</SECTION>\n'
+            '\n')
+        sfile.write(string.Template(template).substitute(translations))
diff --git a/build-aux/qmi-codegen/MessageList.py b/build-aux/qmi-codegen/MessageList.py
index 9cd057c..7d3802d 100644
--- a/build-aux/qmi-codegen/MessageList.py
+++ b/build-aux/qmi-codegen/MessageList.py
@@ -229,3 +229,25 @@ class MessageList:
         utils.add_separator(cfile, 'Service-specific printable', self.service);
         self.__emit_get_printable(hfile, cfile)
         self.__emit_get_version_introduced(hfile, cfile)
+
+    """
+    Emit the sections
+    """
+    def emit_sections(self, sfile):
+        # Emit all message sections
+        for message in self.list:
+            message.emit_sections(sfile)
+
+        translations = { 'hyphened' : utils.build_dashed_name (self.service + 'Private'),
+                         'service'  : utils.build_underscore_name (self.service) }
+
+        # Emit dummy section for service-specific private methods
+        template = (
+            '<SECTION>\n'
+            '<FILE>${hyphened}</FILE>\n'
+            '<SUBSECTION Private>\n'
+            'qmi_message_${service}_get_printable\n'
+            'qmi_message_${service}_get_version_introduced\n'
+            '</SECTION>\n'
+            '\n')
+        sfile.write(string.Template(template).substitute(translations))
diff --git a/build-aux/qmi-codegen/TypeFactory.py b/build-aux/qmi-codegen/TypeFactory.py
index 302b666..da1a185 100644
--- a/build-aux/qmi-codegen/TypeFactory.py
+++ b/build-aux/qmi-codegen/TypeFactory.py
@@ -71,3 +71,29 @@ def set_get_printable_emitted(type_name):
     else:
         emitted_get_printable.append(type_name)
         return True
+
+
+"""
+List to keep track of sections already emitted to the source/header files.
+"""
+emitted_sections = []
+
+"""
+Checks whether a given section has already been emitted.
+"""
+def is_section_emitted(section_name):
+    for i in emitted_sections:
+        if i == section_name:
+            return True
+    else:
+        return False
+
+"""
+Sets the given section as already emitted.
+"""
+def set_section_emitted(section_name):
+    if is_section_emitted(section_name):
+        return False
+    else:
+        emitted_sections.append(section_name)
+        return True
diff --git a/build-aux/qmi-codegen/Variable.py b/build-aux/qmi-codegen/Variable.py
index 8232e48..6eb65d6 100644
--- a/build-aux/qmi-codegen/Variable.py
+++ b/build-aux/qmi-codegen/Variable.py
@@ -125,7 +125,19 @@ class Variable:
         return ''
 
     """
+    Documentation for the struct field
+    """
+    def build_struct_field_documentation(self, line_prefix, variable_name):
+        return ''
+
+    """
     Emits the code to dispose the variable.
     """
     def build_dispose(self, line_prefix, variable_name):
         return ''
+
+    """
+    Add sections
+    """
+    def add_sections(self, sections):
+        pass
diff --git a/build-aux/qmi-codegen/VariableArray.py b/build-aux/qmi-codegen/VariableArray.py
index f5bc65f..d582a6a 100644
--- a/build-aux/qmi-codegen/VariableArray.py
+++ b/build-aux/qmi-codegen/VariableArray.py
@@ -318,7 +318,7 @@ class VariableArray(Variable):
                          'name'                        : variable_name }
 
         template = (
-            '${lp}@${name}: a placeholder for the output #GArray of #${public_array_element_format} elements, or #NULL if not required. Do not free it, it is owned by @self.\n')
+            '${lp}@${name}: a placeholder for the output #GArray of #${public_array_element_format} elements, or %NULL if not required. Do not free it, it is owned by @self.\n')
         return string.Template(template).substitute(translations)
 
 
@@ -382,6 +382,19 @@ class VariableArray(Variable):
 
 
     """
+    Documentation for the struct field
+    """
+    def build_struct_field_documentation(self, line_prefix, variable_name):
+        translations = { 'lp'                          : line_prefix,
+                         'public_array_element_format' : self.array_element.public_format,
+                         'name'                        : variable_name }
+
+        template = (
+            '${lp}@${name}: a #GArray of #${public_array_element_format} elements.\n')
+        return string.Template(template).substitute(translations)
+
+
+    """
     Dispose the array just with an unref
     """
     def build_dispose(self, line_prefix, variable_name):
@@ -392,3 +405,10 @@ class VariableArray(Variable):
             '${lp}if (${variable_name})\n'
             '${lp}    g_array_unref (${variable_name});\n')
         return string.Template(template).substitute(translations)
+
+
+    """
+    Add sections
+    """
+    def add_sections(self, sections):
+        self.array_element.add_sections(sections)
diff --git a/build-aux/qmi-codegen/VariableInteger.py b/build-aux/qmi-codegen/VariableInteger.py
index 96642da..0bb2a2c 100644
--- a/build-aux/qmi-codegen/VariableInteger.py
+++ b/build-aux/qmi-codegen/VariableInteger.py
@@ -233,7 +233,7 @@ class VariableInteger(Variable):
                          'name'          : variable_name }
 
         template = (
-            '${lp}@${name}: a placeholder for the output #${public_format}, or #NULL if not required.\n')
+            '${lp}@${name}: a placeholder for the output #${public_format}, or %NULL if not required.\n')
         return string.Template(template).substitute(translations)
 
     """
@@ -298,3 +298,16 @@ class VariableInteger(Variable):
         template = (
             '${lp}${to} = ${cast_ini}${from}${cast_end};\n')
         return string.Template(template).substitute(translations)
+
+
+    """
+    Documentation for the struct field
+    """
+    def build_struct_field_documentation(self, line_prefix, variable_name):
+        translations = { 'lp'            : line_prefix,
+                         'public_format' : self.public_format,
+                         'name'          : variable_name }
+
+        template = (
+            '${lp}@${name}: a #${public_format}.\n')
+        return string.Template(template).substitute(translations)
diff --git a/build-aux/qmi-codegen/VariableSequence.py b/build-aux/qmi-codegen/VariableSequence.py
index 6e6777a..07b3ba4 100644
--- a/build-aux/qmi-codegen/VariableSequence.py
+++ b/build-aux/qmi-codegen/VariableSequence.py
@@ -204,3 +204,12 @@ class VariableSequence(Variable):
         for member in self.members:
             built += member['object'].build_dispose(line_prefix, variable_name + '_' + member['name'])
         return built
+
+
+    """
+    Add sections
+    """
+    def add_sections(self, sections):
+        # Add sections for each member
+        for member in self.members:
+            member['object'].add_sections(sections)
diff --git a/build-aux/qmi-codegen/VariableString.py b/build-aux/qmi-codegen/VariableString.py
index 7e977c2..c6acbe0 100644
--- a/build-aux/qmi-codegen/VariableString.py
+++ b/build-aux/qmi-codegen/VariableString.py
@@ -219,7 +219,7 @@ class VariableString(Variable):
                          'name' : variable_name }
 
         template = (
-            '${lp}@${name}: a placeholder for the output constant string, or #NULL if not required.\n')
+            '${lp}@${name}: a placeholder for the output constant string, or %NULL if not required.\n')
         return string.Template(template).substitute(translations)
 
 
@@ -315,6 +315,27 @@ class VariableString(Variable):
 
 
     """
+    Documentation for the struct field
+    """
+    def build_struct_field_documentation(self, line_prefix, variable_name):
+        translations = { 'lp'   : line_prefix,
+                         'name' : variable_name }
+
+        if self.is_fixed_size:
+            translations['fixed_size'] = self.fixed_size
+            template = (
+                '${lp}@${name}: a string of exactly ${fixed_size} characters.\n')
+        elif self.max_size != '':
+            translations['max_size'] = self.max_size
+            template = (
+                '${lp}@${name}: a string with a maximum length of ${max_size} characters.\n')
+        else:
+            template = (
+                '${lp}@${name}: a string.\n')
+        return string.Template(template).substitute(translations)
+
+
+    """
     Dispose the string
     """
     def build_dispose(self, line_prefix, variable_name):
diff --git a/build-aux/qmi-codegen/VariableStruct.py b/build-aux/qmi-codegen/VariableStruct.py
index 5b582b2..c22d9c2 100644
--- a/build-aux/qmi-codegen/VariableStruct.py
+++ b/build-aux/qmi-codegen/VariableStruct.py
@@ -67,6 +67,16 @@ class VariableStruct(Variable):
         translations = { 'format' : self.public_format }
         template = (
             '\n'
+            '/**\n'
+            ' * ${format}:\n')
+        f.write(string.Template(template).substitute(translations))
+        for member in self.members:
+            f.write(member['object'].build_struct_field_documentation(' * ', member['name']))
+
+        template = (
+            ' *\n'
+            ' * A ${format} struct.\n'
+            ' */\n'
             'typedef struct _${format} {\n')
         f.write(string.Template(template).substitute(translations))
 
@@ -173,7 +183,7 @@ class VariableStruct(Variable):
                          'name'   : variable_name }
 
         template = (
-            '${lp}@${name}: a placeholder for the output constant #${format}, or #NULL if not required.\n')
+            '${lp}@${name}: a placeholder for the output constant #${format}, or %NULL if not required.\n')
         return string.Template(template).substitute(translations)
 
 
@@ -235,6 +245,19 @@ class VariableStruct(Variable):
 
 
     """
+    Documentation for the struct field
+    """
+    def build_struct_field_documentation(self, line_prefix, variable_name):
+        translations = { 'lp'     : line_prefix,
+                         'format' : self.public_format,
+                         'name'   : variable_name }
+
+        template = (
+            '${lp}@${name}: a #${format} struct.\n')
+        return string.Template(template).substitute(translations)
+
+
+    """
     Disposing a struct is just about disposing each of the struct fields one by
     one.
     """
@@ -243,3 +266,14 @@ class VariableStruct(Variable):
         for member in self.members:
             built += member['object'].build_dispose(line_prefix, variable_name + '.' + member['name'])
         return built
+
+
+    """
+    Add sections
+    """
+    def add_sections(self, sections):
+        # Add sections for each member
+        for member in self.members:
+            member['object'].add_sections(sections)
+
+        sections['public-types'] += self.public_format + '\n'
diff --git a/build-aux/qmi-codegen/qmi-codegen b/build-aux/qmi-codegen/qmi-codegen
index a25c7f0..38973a2 100755
--- a/build-aux/qmi-codegen/qmi-codegen
+++ b/build-aux/qmi-codegen/qmi-codegen
@@ -48,6 +48,7 @@ def codegen_main():
     # Prepare output file names
     output_file_c = open(opts.output + ".c", 'w')
     output_file_h = open(opts.output + ".h", 'w')
+    output_file_sections = open(opts.output + ".sections", 'w')
 
     # Load all common types
     common_object_list_json = []
@@ -79,10 +80,15 @@ def codegen_main():
     client = Client(object_list_json)
     client.emit(output_file_h, output_file_c, message_list)
 
+    # Emit sections
+    client.emit_sections(output_file_sections)
+    message_list.emit_sections(output_file_sections)
+
     utils.add_header_stop(output_file_h, os.path.basename(opts.output))
 
     output_file_c.close()
     output_file_h.close()
+    output_file_sections.close()
 
     sys.exit(0)