qmi-codegen: avoid documenting internal methods and types

7 files changed, 126 insertions, 101 deletions

diff --git a/build-aux/qmi-codegen/Container.py b/build-aux/qmi-codegen/Container.py
index 1f6f782..5774035 100644
--- a/build-aux/qmi-codegen/Container.py
+++ b/build-aux/qmi-codegen/Container.py
@@ -125,16 +125,18 @@ class Container:
     def __emit_types(self, hfile, cfile, translations):
         translations['type_macro'] = 'QMI_TYPE_' + utils.remove_prefix(utils.build_underscore_uppercase_name(self.fullname), 'QMI_')
         # 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'
-            ' * Since: ${since}\n'
-            ' */\n'
+        template = '\n'
+        if self.static == False:
+            template += (
+                '/**\n'
+                ' * ${camelcase}:\n'
+                ' *\n'
+                ' * The #${camelcase} structure contains private data and should only be accessed\n'
+                ' * using the provided API.\n'
+                ' *\n'
+                ' * Since: ${since}\n'
+                ' */\n')
+        template += (
             'typedef struct _${camelcase} ${camelcase};\n'
             '${static}GType ${underscore}_get_type (void) G_GNUC_CONST;\n'
             '#define ${type_macro} (${underscore}_get_type ())\n')
@@ -169,43 +171,51 @@ class Container:
     """
     def __emit_core(self, hfile, cfile, translations):
         # Emit container core header
-        template = (
-            '\n'
-            '/**\n'
-            ' * ${underscore}_ref:\n'
-            ' * @self: a #${camelcase}.\n'
-            ' *\n'
-            ' * Atomically increments the reference count of @self by one.\n'
-            ' *\n'
-            ' * Returns: the new reference to @self.\n'
-            ' *\n'
-            ' * Since: ${since}\n'
-            ' */\n'
-            '${static}${camelcase} *${underscore}_ref (${camelcase} *self);\n'
-            '\n'
-            '/**\n'
-            ' * ${underscore}_unref:\n'
-            ' * @self: a #${camelcase}.\n'
-            ' *\n'
-            ' * Atomically decrements the reference count of @self by one.\n'
-            ' * If the reference count drops to 0, @self is completely disposed.\n'
-            ' *\n'
-            ' * Since: ${since}\n'
-            ' */\n'
-            '${static}void ${underscore}_unref (${camelcase} *self);\n'
-            'G_DEFINE_AUTOPTR_CLEANUP_FUNC (${camelcase}, ${underscore}_unref);\n')
-        if self.readonly == False:
+        template = '\n'
+        if self.static == False:
             template += (
                 '\n'
                 '/**\n'
-                ' * ${underscore}_new:\n'
+                ' * ${underscore}_ref:\n'
+                ' * @self: a #${camelcase}.\n'
                 ' *\n'
-                ' * Allocates a new #${camelcase}.\n'
+                ' * Atomically increments the reference count of @self by one.\n'
                 ' *\n'
-                ' * Returns: the newly created #${camelcase}. The returned value should be freed with ${underscore}_unref().\n'
+                ' * Returns: the new reference to @self.\n'
                 ' *\n'
                 ' * Since: ${since}\n'
-                ' */\n'
+                ' */\n')
+        template += (
+            '${static}${camelcase} *${underscore}_ref (${camelcase} *self);\n'
+            '\n')
+        if self.static == False:
+            template += (
+                '/**\n'
+                ' * ${underscore}_unref:\n'
+                ' * @self: a #${camelcase}.\n'
+                ' *\n'
+                ' * Atomically decrements the reference count of @self by one.\n'
+                ' * If the reference count drops to 0, @self is completely disposed.\n'
+                ' *\n'
+                ' * Since: ${since}\n'
+                ' */\n')
+        template += (
+            '${static}void ${underscore}_unref (${camelcase} *self);\n'
+            'G_DEFINE_AUTOPTR_CLEANUP_FUNC (${camelcase}, ${underscore}_unref);\n')
+        if self.readonly == False:
+            if self.static == False:
+                template += (
+                    '\n'
+                    '/**\n'
+                    ' * ${underscore}_new:\n'
+                    ' *\n'
+                    ' * Allocates a new #${camelcase}.\n'
+                    ' *\n'
+                    ' * Returns: the newly created #${camelcase}. The returned value should be freed with ${underscore}_unref().\n'
+                    ' *\n'
+                    ' * Since: ${since}\n'
+                    ' */\n')
+            template += (
                 '${static}${camelcase} *${underscore}_new (void);\n')
 
         if self.static:
diff --git a/build-aux/qmi-codegen/Field.py b/build-aux/qmi-codegen/Field.py
index 8e7fa50..5103822 100644
--- a/build-aux/qmi-codegen/Field.py
+++ b/build-aux/qmi-codegen/Field.py
@@ -99,7 +99,7 @@ class Field:
     def emit_types(self, hfile, cfile):
         if TypeFactory.is_type_emitted(self.fullname) is False:
             TypeFactory.set_type_emitted(self.fullname)
-            self.variable.emit_types(hfile, self.since)
+            self.variable.emit_types(hfile, self.since, False)
             self.variable.emit_helper_methods(hfile, cfile)
 
 
@@ -124,20 +124,23 @@ class Field:
                          'static'              : 'static ' if self.static else '' }
 
         # Emit the getter header
-        template = (
-            '\n'
-            '/**\n'
-            ' * ${prefix_underscore}_get_${underscore}:\n'
-            ' * @self: a #${prefix_camelcase}.\n'
-            '${variable_getter_doc}'
-            ' * @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'
-            ' *\n'
-            ' * Since: ${since}\n'
-            ' */\n'
+        template = '\n'
+        if self.static == False:
+            template += (
+                '\n'
+                '/**\n'
+                ' * ${prefix_underscore}_get_${underscore}:\n'
+                ' * @self: a #${prefix_camelcase}.\n'
+                '${variable_getter_doc}'
+                ' * @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'
+                ' *\n'
+                ' * Since: ${since}\n'
+                ' */\n')
+        template += (
             '${static}gboolean ${prefix_underscore}_get_${underscore} (\n'
             '    ${prefix_camelcase} *self,\n'
             '${variable_getter_dec}'
@@ -191,20 +194,23 @@ class Field:
                          'static'              : 'static ' if self.static else '' }
 
         # Emit the setter header
-        template = (
-            '\n'
-            '/**\n'
-            ' * ${prefix_underscore}_set_${underscore}:\n'
-            ' * @self: a #${prefix_camelcase}.\n'
-            '${variable_setter_doc}'
-            ' * @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'
-            ' *\n'
-            ' * Since: ${since}\n'
-            ' */\n'
+        template = '\n'
+        if self.static == False:
+            template += (
+                '\n'
+                '/**\n'
+                ' * ${prefix_underscore}_set_${underscore}:\n'
+                ' * @self: a #${prefix_camelcase}.\n'
+                '${variable_setter_doc}'
+                ' * @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'
+                ' *\n'
+                ' * Since: ${since}\n'
+                ' */\n')
+        template += (
             '${static}gboolean ${prefix_underscore}_set_${underscore} (\n'
             '    ${prefix_camelcase} *self,\n'
             '${variable_setter_dec}'
diff --git a/build-aux/qmi-codegen/FieldResult.py b/build-aux/qmi-codegen/FieldResult.py
index f22f94d..2064e7e 100644
--- a/build-aux/qmi-codegen/FieldResult.py
+++ b/build-aux/qmi-codegen/FieldResult.py
@@ -37,7 +37,7 @@ class FieldResult(Field):
     def emit_types(self, hfile, cfile):
         if TypeFactory.is_type_emitted(self.fullname) is False:
             TypeFactory.set_type_emitted(self.fullname)
-            self.variable.emit_types(cfile, self.since)
+            self.variable.emit_types(cfile, self.since, True)
 
 
     """
@@ -52,19 +52,22 @@ class FieldResult(Field):
                          'since'             : self.since }
 
         # Emit the getter header
-        template = (
-            '\n'
-            '/**\n'
-            ' * ${prefix_underscore}_get_result:\n'
-            ' * @self: a ${prefix_camelcase}.\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'
-            ' *\n'
-            ' * Since: ${since}\n'
-            ' */\n'
+        template = '\n'
+        if self.static == False:
+            template += (
+                '\n'
+                '/**\n'
+                ' * ${prefix_underscore}_get_result:\n'
+                ' * @self: a ${prefix_camelcase}.\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'
+                ' *\n'
+                ' * Since: ${since}\n'
+                ' */\n')
+        template += (
             'gboolean ${prefix_underscore}_get_result (\n'
             '    ${prefix_camelcase} *self,\n'
             '    GError **error);\n')
diff --git a/build-aux/qmi-codegen/Variable.py b/build-aux/qmi-codegen/Variable.py
index 4807c4f..6ae8cc1 100644
--- a/build-aux/qmi-codegen/Variable.py
+++ b/build-aux/qmi-codegen/Variable.py
@@ -67,7 +67,7 @@ class Variable:
     """
     Emits the code to declare specific new types required by the variable.
     """
-    def emit_types(self, f, since):
+    def emit_types(self, f, since, static):
         pass
 
 
diff --git a/build-aux/qmi-codegen/VariableArray.py b/build-aux/qmi-codegen/VariableArray.py
index 630270c..f9cf592 100644
--- a/build-aux/qmi-codegen/VariableArray.py
+++ b/build-aux/qmi-codegen/VariableArray.py
@@ -83,8 +83,8 @@ class VariableArray(Variable):
     """
     Emit the type for the array element
     """
-    def emit_types(self, f, since):
-        self.array_element.emit_types(f, since)
+    def emit_types(self, f, since, static):
+        self.array_element.emit_types(f, since, static)
 
 
     """
diff --git a/build-aux/qmi-codegen/VariableSequence.py b/build-aux/qmi-codegen/VariableSequence.py
index 60ab50b..f8d1e63 100644
--- a/build-aux/qmi-codegen/VariableSequence.py
+++ b/build-aux/qmi-codegen/VariableSequence.py
@@ -56,10 +56,10 @@ class VariableSequence(Variable):
     """
     Emit all types for the members of the sequence
     """
-    def emit_types(self, f, since):
+    def emit_types(self, f, since, static):
         # Emit types for each member
         for member in self.members:
-            member['object'].emit_types(f, since)
+            member['object'].emit_types(f, since, static)
 
 
     """
diff --git a/build-aux/qmi-codegen/VariableStruct.py b/build-aux/qmi-codegen/VariableStruct.py
index a125cff..3567a67 100644
--- a/build-aux/qmi-codegen/VariableStruct.py
+++ b/build-aux/qmi-codegen/VariableStruct.py
@@ -61,27 +61,33 @@ class VariableStruct(Variable):
     """
     Emit all types for the members of the struct plus the new struct type itself
     """
-    def emit_types(self, f, since):
+    def emit_types(self, f, since, static):
         # Emit types for each member
         for member in self.members:
-            member['object'].emit_types(f, since)
+            member['object'].emit_types(f, since, static)
 
         translations = { 'format' : self.public_format,
                          'since'  : since }
-        template = (
-            '\n'
-            '/**\n'
-            ' * ${format}:\n')
+        template = '\n'
         f.write(string.Template(template).substitute(translations))
-        for member in self.members:
-            f.write(member['object'].build_struct_field_documentation(' * ', member['name']))
+
+        if static == False:
+            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'
+                ' * Since: ${since}\n'
+                ' */\n')
+            f.write(string.Template(template).substitute(translations))
 
         template = (
-            ' *\n'
-            ' * A ${format} struct.\n'
-            ' *\n'
-            ' * Since: ${since}\n'
-            ' */\n'
             'typedef struct _${format} {\n')
         f.write(string.Template(template).substitute(translations))