X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gobject%2Fgobject.c;h=29bcccd688412815503311f2c11166023c647c75;hb=bc6ee788b4ff6590513da6ab657448885e92b20b;hp=1da69797ce812a3f963c1fb091af45f784cd5035;hpb=adf892e96af403b8950dff1a370e4270ffaebc62;p=platform%2Fupstream%2Fglib.git
diff --git a/gobject/gobject.c b/gobject/gobject.c
index 1da6979..29bcccd 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -43,16 +43,16 @@
* methods for all object types in GTK+, Pango and other libraries
* based on GObject. The GObject class provides methods for object
* construction and destruction, property access methods, and signal
- * support. Signals are described in detail in .
+ * support. Signals are described in detail [here][gobject-Signals].
+ *
+ * ## Floating references # {#floating-ref}
*
- *
* GInitiallyUnowned is derived from GObject. The only difference between
* the two is that the initial reference of a GInitiallyUnowned is flagged
- * as a floating reference.
- * This means that it is not specifically claimed to be "owned" by
- * any code portion. The main motivation for providing floating references is
- * C convenience. In particular, it allows code to be written as:
+ * as a "floating" reference. This means that it is not specifically
+ * claimed to be "owned" by any code portion. The main motivation for
+ * providing floating references is C convenience. In particular, it
+ * allows code to be written as:
* |[
* container = create_container ();
* container_add_child (container, create_child());
@@ -78,23 +78,24 @@
* language bindings that provide automated reference and memory ownership
* maintenance (such as smart pointers or garbage collection) should not
* expose floating references in their API.
- *
*
* Some object implementations may need to save an objects floating state
* across certain code portions (an example is #GtkMenu), to achieve this,
* the following sequence can be used:
*
* |[
- * /* save floating state */
+ * // save floating state
* gboolean was_floating = g_object_is_floating (object);
* g_object_ref_sink (object);
- * /* protected code portion */
- * ...;
- * /* restore floating state */
+ * // protected code portion
+ *
+ * ...
+ *
+ * // restore floating state
* if (was_floating)
* g_object_force_floating (object);
* else
- * g_object_unref (object); /* release previously acquired reference */
+ * g_object_unref (object); // release previously acquired reference
* ]|
*/
@@ -479,7 +480,7 @@ g_object_do_class_init (GObjectClass *class)
* text_view)
* ]|
* It is important to note that you must use
- * canonical parameter names as
+ * [canonical][canonical-parameter-name] parameter names as
* detail strings for the notify signal.
*/
gobject_signals[NOTIFY] =
@@ -809,11 +810,11 @@ g_object_interface_find_property (gpointer g_iface,
* @name: the name of a property registered in a parent class or
* in an interface of this class.
*
- * Registers @property_id as referring to a property with the
- * name @name in a parent class or in an interface implemented
- * by @oclass. This allows this class to override
- * a property implementation in a parent class or to provide
- * the implementation of a property from an interface.
+ * Registers @property_id as referring to a property with the name
+ * @name in a parent class or in an interface implemented by @oclass.
+ * This allows this class to "override" a property implementation in
+ * a parent class or to provide the implementation of a property from
+ * an interface.
*
* Internally, overriding is implemented by creating a property of type
* #GParamSpecOverride; generally operations that query the properties of
@@ -2240,7 +2241,7 @@ g_object_set (gpointer _object,
* "obj-property", &objval,
* NULL);
*
- * /* Do something with intval, strval, objval */
+ * // Do something with intval, strval, objval
*
* g_free (strval);
* g_object_unref (objval);
@@ -2739,8 +2740,7 @@ object_floating_flag_handler (GObject *object,
* g_object_is_floating:
* @object: (type GObject.Object): a #GObject
*
- * Checks whether @object has a floating
- * reference.
+ * Checks whether @object has a [floating][floating-ref] reference.
*
* Since: 2.10
*
@@ -2759,8 +2759,7 @@ g_object_is_floating (gpointer _object)
* @object: (type GObject.Object): a #GObject
*
* Increase the reference count of @object, and possibly remove the
- * floating reference, if @object
- * has a floating reference.
+ * [floating][floating-ref] reference, if @object has a floating reference.
*
* In other words, if the object is floating, then this call "assumes
* ownership" of the floating reference, converting it to a normal
@@ -2790,11 +2789,10 @@ g_object_ref_sink (gpointer _object)
* g_object_force_floating:
* @object: a #GObject
*
- * This function is intended for #GObject implementations to re-enforce a
- * floating object reference.
- * Doing this is seldom required: all
- * #GInitiallyUnowneds are created with a floating reference which
- * usually just needs to be sunken by calling g_object_ref_sink().
+ * This function is intended for #GObject implementations to re-enforce
+ * a [floating][floating-ref] object reference. Doing this is seldom
+ * required: all #GInitiallyUnowneds are created with a floating reference
+ * which usually just needs to be sunken by calling g_object_ref_sink().
*
* Since: 2.10
*/
@@ -2858,8 +2856,8 @@ toggle_refs_notify (GObject *object,
* to the proxy object, but when there are other references held to
* @object, a strong reference is held. The @notify callback is called
* when the reference from @object to the proxy object should be
- * toggled from strong to weak (@is_last_ref
- * true) or weak to strong (@is_last_ref false).
+ * "toggled" from strong to weak (@is_last_ref true) or weak to strong
+ * (@is_last_ref false).
*
* Since a (normal) reference must be held to the object before
* calling g_object_add_toggle_ref(), the initial state of the reverse
@@ -3931,7 +3929,7 @@ g_object_watch_closure (GObject *object,
/**
* g_closure_new_object:
* @sizeof_closure: the size of the structure to allocate, must be at least
- * sizeof (GClosure)
+ * `sizeof (GClosure)`
* @object: a #GObject pointer to store in the @data field of the newly
* allocated #GClosure
*