[gtk-doc/wip/desrt/fixes-for-glib: 3/5] Ignore standard struct members

[Ryan Lortie <desrt src gnome org>]

commit 27883d943cfcff16f6cfde7ca42ee21c8563c7fb
Author: Xavier Claessens <xavier claessens collabora com>
Date:   Thu Feb 5 12:28:18 2015 -0500

    Ignore standard struct members
    
    https://bugzilla.gnome.org/show_bug.cgi?id=744061

 gtkdoc-common.pl.in         |    3 +++
 gtkdoc-mkdb.in              |    5 +++++
 help/manual/C/index.docbook |   10 +++++++---
 3 files changed, 15 insertions(+), 3 deletions(-)
---
diff --git a/gtkdoc-common.pl.in b/gtkdoc-common.pl.in
index c6a0403..4747396 100644
--- a/gtkdoc-common.pl.in
+++ b/gtkdoc-common.pl.in
@@ -120,6 +120,9 @@ sub ParseStructDeclaration {
     $declaration =~ s \n\s*// *?\n \n@msg;
     $declaration =~ s@//.*@@g;
 
+    # Remove g_iface, parent_instance and parent_class if they are first member
+    $declaration =~ s/(\{)\s*(\w)+\s+(g_iface|parent_instance|parent_class)\s*;/$1/g;
+
     my @result = ();
 
     if ($declaration =~ /^\s*$/) {
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index 9543a3c..11d3f59 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -1766,6 +1766,11 @@ EOF
         }
         $desc .= "</tbody></tgroup></informaltable>\n</refsect3>\n";
         foreach my $field_name (keys %field_descrs) {
+            # Documenting those standard fields is not required anymore, but
+            # we don't want to warn if they are documented anyway.
+            if ($field_name =~ /(g_iface|parent_instance|parent_class)/) {
+                next;
+            }
             &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
                 "Field description for $symbol"."::"."$field_name is not used from source code comment 
block.");
             if ($unused_parameters ne "") {
diff --git a/help/manual/C/index.docbook b/help/manual/C/index.docbook
index ac614b2..22d9d94 100644
--- a/help/manual/C/index.docbook
+++ b/help/manual/C/index.docbook
@@ -1218,10 +1218,8 @@ foo_signals[FOOBARIZE] =
  * This is the best widget, ever.
  */
 typedef struct _FooWidget {
-  /*< private >*/
-  GtkWidget parent;
+  GtkWidget parent_instance;
 
-  /*< public >*/
   gboolean bar;
 } FooWidget;
 ]]></programlisting>
@@ -1234,6 +1232,12 @@ typedef struct _FooWidget {
         </para>
 
         <para>
+          If the first field is "g_iface", "parent_instance" or "parent_class"
+          it will be considered private automatically and doesn't need to be
+          mentioned in the comment block.
+        </para>
+
+        <para>
           Struct comment blocks can also be used for GObjects and GObjectClasses.
           It is usually a good idea to add a comment block for a class, if it has
           vmethods (as this is how they can be documented). For the GObject