From 60b623d3fb70c09cb08e6c088b76c59d4316e132 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 1 Feb 2014 10:19:07 -0500 Subject: [PATCH] GObject: Convert docs to markdown In particular, convert lists to markdown syntax. --- gobject/gclosure.c | 27 ++++++++------------ gobject/gobject.c | 65 ++++++---------------------------------------- gobject/gsignal.c | 29 +++++++++------------ gobject/gtypemodule.c | 30 ++++++++-------------- gobject/gtypeplugin.c | 71 ++++++++++++++++++++++----------------------------- 5 files changed, 72 insertions(+), 150 deletions(-) diff --git a/gobject/gclosure.c b/gobject/gclosure.c index 9cc6464..4ec51ef 100644 --- a/gobject/gclosure.c +++ b/gobject/gclosure.c @@ -71,22 +71,17 @@ * * Using closures has a number of important advantages over a simple * callback function/data pointer combination: - * - * - * Closures allow the callee to get the types of the callback parameters, - * which means that language bindings don't have to write individual glue - * for each callback type. - * - * - * The reference counting of #GClosure makes it easy to handle reentrancy - * right; if a callback is removed while it is being invoked, the closure - * and its parameters won't be freed until the invocation finishes. - * - * - * g_closure_invalidate() and invalidation notifiers allow callbacks to be - * automatically removed when the objects they point to go away. - * - * + * + * - Closures allow the callee to get the types of the callback parameters, + * which means that language bindings don't have to write individual glue + * for each callback type. + * + * - The reference counting of #GClosure makes it easy to handle reentrancy + * right; if a callback is removed while it is being invoked, the closure + * and its parameters won't be freed until the invocation finishes. + * + * - g_closure_invalidate() and invalidation notifiers allow callbacks to be + * automatically removed when the objects they point to go away. */ #define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1) diff --git a/gobject/gobject.c b/gobject/gobject.c index 258f996..b404a9d 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -2399,63 +2399,14 @@ g_object_get_property (GObject *object, * * The signal specs expected by this function have the form * "modifier::signal_name", where modifier can be one of the following: - * - * - * signal - * - * equivalent to g_signal_connect_data (..., NULL, 0) - * - * - * - * object_signal - * object-signal - * - * equivalent to g_signal_connect_object (..., 0) - * - * - * - * swapped_signal - * swapped-signal - * - * equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) - * - * - * - * swapped_object_signal - * swapped-object-signal - * - * equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) - * - * - * - * signal_after - * signal-after - * - * equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) - * - * - * - * object_signal_after - * object-signal-after - * - * equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) - * - * - * - * swapped_signal_after - * swapped-signal-after - * - * equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) - * - * - * - * swapped_object_signal_after - * swapped-object-signal-after - * - * equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) - * - * - * + * * - signal: equivalent to g_signal_connect_data (..., NULL, 0) + * - object-signal, object_signal: equivalent to g_signal_connect_object (..., 0) + * - swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) + * - swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) + * - signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) + * - object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) + * - swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) + * - swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) * * |[ * menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 8115022..2110d09 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -65,23 +65,18 @@ * certain signal on certain object instances. * * A signal emission consists of five stages, unless prematurely stopped: - * - * - * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - * - * - * 2 - Invocation of normal user-provided signal handlers (where the @after flag is not set) - * - * - * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - * - * - * 4 - Invocation of user provided signal handlers (where the @after flag is set) - * - * - * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * - * + * + * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals + * + * 2. Invocation of normal user-provided signal handlers (where the @after + * flag is not set) + * + * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals + * + * 4. Invocation of user provided signal handlers (where the @after flag is set) + * + * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals + * The user-provided signal handlers are called in the order they were * connected in. * diff --git a/gobject/gtypemodule.c b/gobject/gtypemodule.c index a8d5510..35d13e2 100644 --- a/gobject/gtypemodule.c +++ b/gobject/gtypemodule.c @@ -26,30 +26,20 @@ /** * SECTION:gtypemodule * @short_description: Type loading modules - * @see_also: - * - * #GTypePlugin - * The abstract type loader interface. - * - * - * #GModule - * Portable mechanism for dynamically loaded modules. - * - * + * @see_also: #GTypePlugin, #GModule * @title: GTypeModule * * #GTypeModule provides a simple implementation of the #GTypePlugin * interface. The model of #GTypeModule is a dynamically loaded module - * which implements some number of types and interface - * implementations. When the module is loaded, it registers its types - * and interfaces using g_type_module_register_type() and - * g_type_module_add_interface(). As long as any instances of these - * types and interface implementations are in use, the module is kept - * loaded. When the types and interfaces are gone, the module may be - * unloaded. If the types and interfaces become used again, the module - * will be reloaded. Note that the last unref cannot happen in module - * code, since that would lead to the caller's code being unloaded before - * g_object_unref() returns to it. + * which implements some number of types and interface implementations. + * When the module is loaded, it registers its types and interfaces + * using g_type_module_register_type() and g_type_module_add_interface(). + * As long as any instances of these types and interface implementations + * are in use, the module is kept loaded. When the types and interfaces + * are gone, the module may be unloaded. If the types and interfaces + * become used again, the module will be reloaded. Note that the last + * unref cannot happen in module code, since that would lead to the + * caller's code being unloaded before g_object_unref() returns to it. * * Keeping track of whether the module should be loaded or not is done by * using a use count - it starts at zero, and whenever it is greater than diff --git a/gobject/gtypeplugin.c b/gobject/gtypeplugin.c index 13fc989..c29258c 100644 --- a/gobject/gtypeplugin.c +++ b/gobject/gtypeplugin.c @@ -26,49 +26,40 @@ * @see_also: #GTypeModule and g_type_register_dynamic(). * @title: GTypePlugin * - * The GObject type system supports dynamic loading of types. The - * #GTypePlugin interface is used to handle the lifecycle of - * dynamically loaded types. It goes as follows: + * The GObject type system supports dynamic loading of types. + * The #GTypePlugin interface is used to handle the lifecycle + * of dynamically loaded types. It goes as follows: * - * - * - * The type is initially introduced (usually upon loading the module - * the first time, or by your main application that knows what modules - * introduces what types), like this: - * |[ - * new_type_id = g_type_register_dynamic (parent_type_id, - * "TypeName", - * new_type_plugin, - * type_flags); - * ]| - * where new_type_plugin is an implementation of the - * #GTypePlugin interface. - * - * - * The type's implementation is referenced, e.g. through + * 1. The type is initially introduced (usually upon loading the module + * the first time, or by your main application that knows what modules + * introduces what types), like this: + * |[ + * new_type_id = g_type_register_dynamic (parent_type_id, + * "TypeName", + * new_type_plugin, + * type_flags); + * ]| + * where @new_type_plugin is an implementation of the + * #GTypePlugin interface. + * + * 2. The type's implementation is referenced, e.g. through * g_type_class_ref() or through g_type_create_instance() (this is * being called by g_object_new()) or through one of the above done on - * a type derived from new_type_id. - * - * - * This causes the type system to load the type's implementation by calling - * g_type_plugin_use() and g_type_plugin_complete_type_info() on - * new_type_plugin. - * - * - * At some point the type's implementation isn't required anymore, e.g. after - * g_type_class_unref() or g_type_free_instance() (called when the reference - * count of an instance drops to zero). - * - * - * This causes the type system to throw away the information retrieved from - * g_type_plugin_complete_type_info() and then it calls - * g_type_plugin_unuse() on new_type_plugin. - * - * - * Things may repeat from the second step. - * - * + * a type derived from @new_type_id. + * + * 3. This causes the type system to load the type's implementation by + * calling g_type_plugin_use() and g_type_plugin_complete_type_info() + * on @new_type_plugin. + * + * 4. At some point the type's implementation isn't required anymore, + * e.g. after g_type_class_unref() or g_type_free_instance() (called + * when the reference count of an instance drops to zero). + * + * 5. This causes the type system to throw away the information retrieved + * from g_type_plugin_complete_type_info() and then it calls + * g_type_plugin_unuse() on @new_type_plugin. + * + * 6. Things may repeat from the second step. * * So basically, you need to implement a #GTypePlugin type that * carries a use_count, once use_count goes from zero to one, you need -- 2.7.4