docs: Update the coding style

We should mention that newly written code should not have the private
data pointer in the instance structure, and that private data should be
added using the new GObject macros.

https://bugzilla.gnome.org/show_bug.cgi?id=702996

1 files changed, 15 insertions, 9 deletions

diff --git a/docs/CODING-STYLE b/docs/CODING-STYLE
index ae6e9fbc7c..6ee0a971ad 100644
--- a/docs/CODING-STYLE
+++ b/docs/CODING-STYLE
@@ -499,8 +499,9 @@ And callback types:
   typedef void (* GtkCallback) (GtkWidget *widget,
                                 gpointer   user_data);
 
-Instance structures should only contain the parent type and a pointer to a
-private data structure, and they should be annotated as "private":
+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:
 
   struct _GtkFoo
   {
@@ -510,21 +511,26 @@ private data structure, and they should be annotated as "private":
     GtkFooPrivate *priv;
   };
 
+The private data pointer is optional and should be omitted in newly
+written classes.
+
+Always use the G_DEFINE_TYPE(), G_DEFINE_TYPE_WITH_PRIVATE(), and
+G_DEFINE_TYPE_WITH_CODE() macros, or their abstract variants
+G_DEFINE_ABSTRACT_TYPE(), G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE(), and
+G_DEFINE_ABSTRACT_TYPE_WITH_CODE(); also, use the similar macros for
+defining interfaces and boxed types.
+
 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.
 
-The private data structure should only be accessed internally using the
-pointer inside the instance structure, and never using the
+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
 G_TYPE_INSTANCE_GET_PRIVATE() macro or the g_type_instance_get_private()
 function.
 
-Always use the G_DEFINE_TYPE(), G_DEFINE_TYPE_WITH_CODE() macros, or
-their abstract variants G_DEFINE_ABSTRACT_TYPE() and
-G_DEFINE_ABSTRACT_TYPE_WITH_CODE(), and the similar macros for defining
-interfaces.
-
 Interface types should always have the dummy typedef for cast purposes:
 
         typedef struct _GtkFoo              GtkFoo;