[gnome-devel-docs] programming-guidelines: Add recommendation to use G_DECLARE_*_TYPE macros

[Philip Withnall <pwithnall src gnome org>]

commit 2993b16ee3d8339ff79cff71006b3f257c071238
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Mon Feb 9 19:19:25 2015 +0000

    programming-guidelines: Add recommendation to use G_DECLARE_*_TYPE macros
    
    Use the new G_DECLARE_FINAL_TYPE and G_DECLARE_DERIVABLE_TYPE hotness
    macros from GLib.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=376123

 programming-guidelines/C/c-coding-style.page |   65 ++++++++++++++-----------
 1 files changed, 36 insertions(+), 29 deletions(-)
---
diff --git a/programming-guidelines/C/c-coding-style.page b/programming-guidelines/C/c-coding-style.page
index cadfbcf..823ca50 100644
--- a/programming-guidelines/C/c-coding-style.page
+++ b/programming-guidelines/C/c-coding-style.page
@@ -766,9 +766,8 @@ G_END_DECLS
     </p>
 
     <code style="valid">
-typedef struct _GtkFoo          GtkFoo;
-typedef struct _GtkFooClass     GtkFooClass;
-typedef struct _GtkFooPrivate   GtkFooPrivate;</code>
+typedef struct _GtkBoxedStruct       GtkBoxedStruct;
+typedef struct _GtkMoreBoxedStruct   GtkMoreBoxedStruct;</code>
 
     <p>
       This includes enumeration types:
@@ -790,25 +789,49 @@ typedef void (* GtkCallback) (GtkWidget *widget,
                               gpointer   user_data);</code>
 
     <p>
-      Instance structures should only contain the parent type, and optionally a
-      pointer to a private data structure, and they should be annotated as
-      ‘private’ using the gtk-doc trigraph:
+      Instance structures should be declared using
+      <code>G_DECLARE_FINAL_TYPE</code> or
+      <code>G_DECLARE_DERIVABLE_TYPE</code>:
+    </p>
+
+    <code style="valid">
+#define GTK_TYPE_FOO (gtk_foo_get_type ())
+G_DECLARE_FINAL_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)</code>
+
+    <p>
+      For final types, private data can be stored in the object struct, which
+      should be defined in the C file:
     </p>
 
     <code style="valid">
 struct _GtkFoo
 {
-  /*&lt; private &gt;*/
-  GtkWidget parent_instance;
+  GObject   parent_instance;
 
-  GtkFooPrivate *priv;
+  guint     private_data;
+  gpointer  more_private_data;
 };</code>
 
     <p>
-      The private data pointer is optional and should be omitted in newly
-      written classes.
+      For derivable types, private data must be stored in a private struct in
+      the C file, configured using <code>G_DEFINE_TYPE_WITH_PRIVATE()</code>
+      and accessed using a <code>_get_instance_private()</code> function:
     </p>
 
+    <code style="valid">
+#define GTK_TYPE_FOO gtk_foo_get_type ()
+G_DECLARE_DERIVABLE_TYPE (GtkFoo, gtk_foo, GTK, FOO, GtkWidget)
+
+struct _GtkFooClass
+{
+  GtkWidgetClass parent_class;
+
+  void (* handle_frob)  (GtkFrobber *frobber,
+                         guint       n_frobs);
+
+  gpointer padding[12];
+};</code>
+
     <p>
       Always use the <code>G_DEFINE_TYPE()</code>,
       <code>G_DEFINE_TYPE_WITH_PRIVATE()</code>, and
@@ -820,28 +843,12 @@ struct _GtkFoo
     </p>
 
     <p>
-      All the properties should be stored inside the private data
-      structure, which is defined inside the source file — or, if
-      needed, inside a private header file; the private header
-      filename must end with ‘private.h’ and must not be installed.
-    </p>
-
-    <p>
-      The private data structure should only be accessed internally
-      either using the pointer inside the instance structure, if one
-      is available, or the generated instance private data getter
-      function for your type. You should never use the
-      <code>G_TYPE_INSTANCE_GET_PRIVATE()</code> macro or the
-      <code>g_type_instance_get_private()</code> function.
-    </p>
-
-    <p>
       Interface types should always have the dummy typedef for cast
       purposes:
     </p>
 
     <code style="valid">
-typedef struct _GtkFoo              GtkFoo;</code>
+typedef struct _GtkFooable          GtkFooable;</code>
 
     <p>
       The interface structure should have ‘Interface’ postfixed to the
@@ -849,7 +856,7 @@ typedef struct _GtkFoo              GtkFoo;</code>
     </p>
 
     <code style="valid">
-typedef struct _GtkFooInterface         GtkFooInterface;</code>
+typedef struct _GtkFooableInterface     GtkFooableInterface;</code>
 
     <p>
       Interfaces must have the following macros: