gobject: Add advice on larger alignment requirements for GObject members

We now guarantee that GObjects will always be allocated at least as
aligned as the basic types. If you want to put an element in your
GObject which has higher alignment requirements, we can’t guarantee it
will be aligned*. If you need it to be aligned, you’ll need to put it on
the heap (aligned appropriately), or add appropriate padding in your
GObject struct.

*Actually, GSlice will guarantee that the whole GObject is aligned to at
least the power of 2 greater than or equal to the size of the GObject,
which means any element in the GObject struct should always be
appropriate aligned if the compiler pads it appropriately. If malloc()
is used, however, it doesn’t make that guarantee, so we can’t make that
guarantee overall.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Helps: #1231

gobject/gobject.c

@@ -1798,7 +1798,9 @@ g_object_get_type (void)
  *
  * Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the
  * alignment of the largest basic GLib type (typically this is #guint64 or
- * #gdouble).
+ * #gdouble). If you need larger alignment for an element in a #GObject, you
+ * should allocate it on the heap (aligned), or arrange for your #GObject to be
+ * appropriately padded.
  *
  * Returns: (transfer full) (type GObject.Object): a new instance of
  *   @object_type

gobject/gobject.h

@@ -256,7 +256,11 @@ typedef void (*GWeakNotify)		(gpointer      data,
  *
  * Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the
  * alignment of the largest basic GLib type (typically this is #guint64 or
- * #gdouble).
+ * #gdouble). If you need larger alignment for an element in a #GObject, you
+ * should allocate it on the heap (aligned), or arrange for your #GObject to be
+ * appropriately padded. This guarantee applies to the #GObject (or derived)
+ * struct, the #GObjectClass (or derived) struct, and any private data allocated
+ * by G_ADD_PRIVATE().
  */
 struct  _GObject
 {

gobject/gtype.h

@@ -1983,7 +1983,9 @@ guint     g_type_get_type_registration_serial (void);
  *
  * Since GLib 2.72, the returned `MyObjectPrivate` pointer is guaranteed to be
  * aligned to at least the alignment of the largest basic GLib type (typically
- * this is #guint64 or #gdouble).
+ * this is #guint64 or #gdouble). If you need larger alignment for an element in
+ * the struct, you should allocate it on the heap (aligned), or arrange for your
+ * `MyObjectPrivate` struct to be appropriately padded.
  *
  * Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
  * macros, since it depends on variable names from those macros.