[gtk+] Move documentation to inline comments: GtkObject

[Javier Jardón <jjardon src gnome org>]

commit 157d618d6bba7fa5b06af4f0060e719d7bec2412
Author: Javier Jardón <jjardon gnome org>
Date:   Thu May 13 19:39:44 2010 +0200

    Move documentation to inline comments: GtkObject

 docs/reference/gtk/tmpl/.gitignore     |    1 +
 docs/reference/gtk/tmpl/gtkobject.sgml |  146 --------------------------------
 gtk/gtkobject.c                        |   91 ++++++++++++++++++++
 gtk/gtkobject.h                        |   16 +++-
 4 files changed, 107 insertions(+), 147 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 8b4eaa0..d8fbb17 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -3,6 +3,7 @@ gtkbox.sgml
 gtkbuilder.sgml
 gtkhbox.sgml
 gtkmessagedialog.sgml
+gtkobject.sgml
 gtkorientable.sgml
 gtkpagesetupunixdialog.sgml
 gtkseparator.sgml
diff --git a/gtk/gtkobject.c b/gtk/gtkobject.c
index 9cedfe3..a393070 100644
--- a/gtk/gtkobject.c
+++ b/gtk/gtkobject.c
@@ -38,6 +38,77 @@
 #include "gtkalias.h"
 
 
+/**
+ * SECTION:gtkobject
+ * @Short_description: The base class of the GTK+ type hierarchy
+ * @Title: GtkObject
+ * @See_also:#GObject
+ *
+ * #GtkObject is the base class for all widgets, and for a few
+ * non-widget objects such as #GtkAdjustment. #GtkObject predates
+ * #GObject; non-widgets that derive from #GtkObject rather than
+ * #GObject do so for backward compatibility reasons.
+ *
+ * #GtkObject<!-- -->s are created with a "floating" reference count.
+ * This means that the initial reference is not owned by anyone. Calling
+ * g_object_unref() on a newly-created #GtkObject is incorrect, the floating
+ * reference has to be removed first. This can be done by anyone at any time,
+ * by calling g_object_ref_sink() to convert the floating reference into a
+ * regular reference. g_object_ref_sink() returns a new reference if an object
+ * is already sunk (has no floating reference).
+ *
+ * When you add a widget to its parent container, the parent container
+ * will do this:
+ * <informalexample><programlisting>
+ *   g_object_ref_sink (G_OBJECT (child_widget));
+ * </programlisting></informalexample>
+ * This means that the container now owns a reference to the child widget
+ * and the child widget has no floating reference.
+ *
+ * The purpose of the floating reference is to keep the child widget alive
+ * until you add it to a parent container:
+ * <informalexample><programlisting>
+ *    button = gtk_button_new (<!-- -->);
+ *    /&ast; button has one floating reference to keep it alive &ast;/
+ *    gtk_container_add (GTK_CONTAINER (container), button);
+ *    /&ast; button has one non-floating reference owned by the container &ast;/
+ * </programlisting></informalexample>
+ *
+ * #GtkWindow is a special case, because GTK+ itself will ref/sink it on creation.
+ * That is, after calling gtk_window_new(), the #GtkWindow will have one
+ * reference which is owned by GTK+, and no floating references.
+ *
+ * One more factor comes into play: the #GtkObject::destroy signal, emitted by the
+ * gtk_object_destroy() method. The #GtkObject::destroy signal asks all code owning a
+ * reference to an object to release said reference. So, for example, if you call
+ * gtk_object_destroy() on a #GtkWindow, GTK+ will release the reference count that
+ * it owns; if you call gtk_object_destroy() on a #GtkButton, then the button will
+ * be removed from its parent container and the parent container will release its
+ * reference to the button.  Because these references are released, calling
+ * gtk_object_destroy() should result in freeing all memory associated with an
+ * object, unless some buggy code fails to release its references in response to
+ * the #GtkObject::destroy signal. Freeing memory (referred to as
+ * <firstterm>finalization</firstterm>) only happens if the reference count reaches
+ * zero.
+ *
+ * Some simple rules for handling #GtkObject:
+ * <itemizedlist>
+ * <listitem><para>
+ * Never call g_object_unref() unless you have previously called g_object_ref(),
+ * even if you created the #GtkObject. (Note: this is <emphasis>not</emphasis>
+ * true for #GObject; for #GObject, the creator of the object owns a reference.)
+ * </para></listitem>
+ * <listitem><para>
+ * Call gtk_object_destroy() to get rid of most objects in most cases.
+ * In particular, widgets are almost always destroyed in this way.
+ * </para></listitem>
+ * <listitem><para> Because of the floating reference count, you don't need to
+ * worry about reference counting for widgets and toplevel windows, unless you
+ * explicitly call g_object_ref() yourself.</para></listitem>
+ * </itemizedlist>
+ */
+
+
 enum {
   DESTROY,
   LAST_SIGNAL
@@ -112,6 +183,14 @@ gtk_object_class_init (GtkObjectClass *class)
 
   class->destroy = gtk_object_real_destroy;
 
+  /**
+   * GtkObject::destroy:
+   * @object: the object which received the signal.
+   *
+   * Signals that all holders of a reference to the #GtkObject should release
+   * the reference that they hold. May result in finalization of the object
+   * if all references are released.
+   */
   object_signals[DESTROY] =
     g_signal_new (I_("destroy"),
 		  G_TYPE_FROM_CLASS (gobject_class),
@@ -132,6 +211,18 @@ gtk_object_init (GtkObject      *object,
  * Functions to end a GtkObject's life time
  *
  ********************************************/
+/**
+ * gtk_object_destroy:
+ * @object: the object to destroy.
+ *
+ * Emits the #GtkObject::destroy signal notifying all reference holders that they should
+ * release the #GtkObject. See the overview documentation at the top of the
+ * page for more details.
+ *
+ * The memory for the object itself won't be deleted until
+ * its reference count actually drops to 0; gtk_object_destroy() merely asks
+ * reference holders to release their references, it does not free the object.
+ */
 void
 gtk_object_destroy (GtkObject *object)
 {
diff --git a/gtk/gtkobject.h b/gtk/gtkobject.h
index b20f249..34f34ed 100644
--- a/gtk/gtkobject.h
+++ b/gtk/gtkobject.h
@@ -56,6 +56,15 @@ G_BEGIN_DECLS
  * is a kinda nasty break up, it does make the size of
  * derived objects smaller.
  */
+/**
+ * GtkObjectFlags:
+ * @GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used
+ *   internally by GTK+ to prevent reinvokations during destruction.
+ * @GTK_RESERVED_1: reserved for future use
+ * @GTK_RESERVED_2: reserved for future use
+ *
+ * Tells about the state of the object.
+ */
 typedef enum
 {
   GTK_IN_DESTRUCTION	= 1 << 0, /* Used internally during dispose */
@@ -63,7 +72,12 @@ typedef enum
   GTK_RESERVED_2	= 1 << 3
 } GtkObjectFlags;
 
-/* Macros for extracting the object_flags from GtkObject.
+/**
+ * GTK_OBJECT_FLAGS:
+ * @obj: the object whose flags are returned.
+ *
+ * Gets the #GtkObjectFlags for an object without directly
+ * accessing its members.
  */
 #define GTK_OBJECT_FLAGS(obj)		  (GTK_OBJECT (obj)->flags)