remove trailing whitespace from newly added gtk-doc comments and

2008-06-22  Michael Natterer  <mitch@imendio.com>

	* *.c: remove trailing whitespace from newly added gtk-doc
	comments and reformatted some where they contained overly long or
	ill-formatted lines.


svn path=/trunk/; revision=7090
This commit is contained in:
Michael Natterer
2008-06-22 14:53:09 +00:00
committed by Michael Natterer
parent 5602b7e275
commit 6347be5fb6
16 changed files with 1225 additions and 1098 deletions

View File

@@ -30,9 +30,12 @@
#include "gvalue.h"
#include "gobjectalias.h"
/**
* SECTION:gclosure
*
* @Short_description: Functions as first-class objects
*
* @Title: Closures
*
* A #GClosure represents a callback supplied by the programmer. It
@@ -84,6 +87,7 @@
* </itemizedlist>
*/
#define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1)
#define CLOSURE_MAX_N_GUARDS ((1 << 1) - 1)
#define CLOSURE_MAX_N_FNOTIFIERS ((1 << 2) - 1)
@@ -144,47 +148,47 @@ enum {
/* --- functions --- */
/**
* g_closure_new_simple:
* @sizeof_closure: the size of the structure to allocate, must be at least
* <literal>sizeof (GClosure)</literal>
* @sizeof_closure: the size of the structure to allocate, must be at least
* <literal>sizeof (GClosure)</literal>
* @data: data to store in the @data field of the newly allocated #GClosure
*
* Allocates a struct of the given size and initializes the initial part
* as a #GClosure. This function is mainly useful when implementing new types
* of closures.
*
*
* Allocates a struct of the given size and initializes the initial
* part as a #GClosure. This function is mainly useful when
* implementing new types of closures.
*
* |[
* typedef struct _MyClosure MyClosure;
* struct _MyClosure
* struct _MyClosure
* {
* GClosure closure;
* // extra data goes here
* };
*
* };
*
* static void
* my_closure_finalize (gpointer notify_data,
* my_closure_finalize (gpointer notify_data,
* GClosure *closure)
* {
* MyClosure *my_closure = (MyClosure *)closure;
*
*
* // free extra data here
* }
*
*
* MyClosure *my_closure_new (gpointer data)
* {
* GClosure *closure;
* MyClosure *my_closure;
*
*
* closure = g_closure_new_simple (sizeof (MyClosure), data);
* my_closure = (MyClosure *) closure;
*
*
* // initialize extra data here
*
*
* g_closure_add_finalize_notifier (closure, notify_data,
* my_closure_finalize);
* return my_closure;
* }
* ]|
*
*
* Returns: a newly allocated #GClosure
*/
GClosure*
@@ -296,20 +300,22 @@ closure_invoke_notifiers (GClosure *closure,
* @closure: a #GClosure
* @marshal_data: context-dependent data to pass to @meta_marshal
* @meta_marshal: a #GClosureMarshal function
*
* Sets the meta marshaller of @closure.
* A meta marshaller wraps @closure->marshal and modifies the way it is called
* in some fashion. The most common use of this facility is for C callbacks.
* The same marshallers (generated by
* <link linkend="glib-genmarshal">glib-genmarshal</link>) are used everywhere,
* but the way that we get the callback function differs. In most cases we want
* to use @closure->callback, but in other cases we want to use some
* different technique to retrieve the callback function.
*
* For example, class closures for signals (see g_signal_type_cclosure_new())
* retrieve the callback function from a fixed offset in the class structure.
* The meta marshaller retrieves the right callback and passes it to the
* marshaller as the @marshal_data argument.
*
* Sets the meta marshaller of @closure. A meta marshaller wraps
* @closure->marshal and modifies the way it is called in some
* fashion. The most common use of this facility is for C callbacks.
* The same marshallers (generated by <link
* linkend="glib-genmarshal">glib-genmarshal</link>) are used
* everywhere, but the way that we get the callback function
* differs. In most cases we want to use @closure->callback, but in
* other cases we want to use some different technique to retrieve the
* callback function.
*
* For example, class closures for signals (see
* g_signal_type_cclosure_new()) retrieve the callback function from a
* fixed offset in the class structure. The meta marshaller retrieves
* the right callback and passes it to the marshaller as the
* @marshal_data argument.
*/
void
g_closure_set_meta_marshal (GClosure *closure,
@@ -346,11 +352,11 @@ g_closure_set_meta_marshal (GClosure *closure,
* @pre_marshal_notify: a function to call before the closure callback
* @post_marshal_data: data to pass to @post_marshal_notify
* @post_marshal_notify: a function to call after the closure callback
*
* Adds a pair of notifiers which get invoked before and after the closure
* callback, respectively. This is typically used to protect the extra arguments
* for the duration of the callback. See g_object_watch_closure() for an
* example of marshal guards.
*
* Adds a pair of notifiers which get invoked before and after the
* closure callback, respectively. This is typically used to protect
* the extra arguments for the duration of the callback. See
* g_object_watch_closure() for an example of marshal guards.
*/
void
g_closure_add_marshal_guards (GClosure *closure,
@@ -402,13 +408,13 @@ g_closure_add_marshal_guards (GClosure *closure,
* @closure: a #GClosure
* @notify_data: data to pass to @notify_func
* @notify_func: the callback function to register
*
* Registers a finalization notifier which will be called when the reference
* count of @closure goes down to 0. Multiple finalization notifiers on a
* single closure are invoked in unspecified order. If a single call to
* g_closure_unref() results in the closure being both invalidated and
* finalized, then the invalidate notifiers will be run before the finalize
* notifiers.
*
* Registers a finalization notifier which will be called when the
* reference count of @closure goes down to 0. Multiple finalization
* notifiers on a single closure are invoked in unspecified order. If
* a single call to g_closure_unref() results in the closure being
* both invalidated and finalized, then the invalidate notifiers will
* be run before the finalize notifiers.
*/
void
g_closure_add_finalize_notifier (GClosure *closure,
@@ -438,10 +444,11 @@ g_closure_add_finalize_notifier (GClosure *closure,
* @closure: a #GClosure
* @notify_data: data to pass to @notify_func
* @notify_func: the callback function to register
*
* Registers an invalidation notifier which will be called when the @closure
* is invalidated with g_closure_invalidate(). Invalidation notifiers are
* invoked before finalization notifiers, in an unspecified order.
*
* Registers an invalidation notifier which will be called when the
* @closure is invalidated with g_closure_invalidate(). Invalidation
* notifiers are invoked before finalization notifiers, in an
* unspecified order.
*/
void
g_closure_add_invalidate_notifier (GClosure *closure,
@@ -509,10 +516,10 @@ closure_try_remove_fnotify (GClosure *closure,
/**
* g_closure_ref:
* @closure: #GClosure to increment the reference count on
*
*
* Increments the reference count on a closure to force it staying
* alive while the caller holds a pointer to it.
*
*
* Returns: The @closure passed in, for convenience
*/
GClosure*
@@ -532,18 +539,20 @@ g_closure_ref (GClosure *closure)
/**
* g_closure_invalidate:
* @closure: GClosure to invalidate
*
* Sets a flag on the closure to indicate that it's calling environment has
* become invalid, and thus causes any future invocations of g_closure_invoke()
* on this @closure to be ignored. Also, invalidation notifiers installed on
* the closure will be called at this point. Note that unless you are holding
* a reference to the closure yourself, the invalidation notifiers may unref
* the closure and cause it to be destroyed, so if you need to access the
* closure after calling g_closure_invalidate(), make sure that you've
* previously called g_closure_ref().
*
* Note that g_closure_invalidate() will also be called when the reference count
* of a closure drops to zero (unless it has already been invalidated before).
*
* Sets a flag on the closure to indicate that it's calling
* environment has become invalid, and thus causes any future
* invocations of g_closure_invoke() on this @closure to be
* ignored. Also, invalidation notifiers installed on the closure will
* be called at this point. Note that unless you are holding a
* reference to the closure yourself, the invalidation notifiers may
* unref the closure and cause it to be destroyed, so if you need to
* access the closure after calling g_closure_invalidate(), make sure
* that you've previously called g_closure_ref().
*
* Note that g_closure_invalidate() will also be called when the
* reference count of a closure drops to zero (unless it has already
* been invalidated before).
*/
void
g_closure_invalidate (GClosure *closure)
@@ -565,10 +574,10 @@ g_closure_invalidate (GClosure *closure)
/**
* g_closure_unref:
* @closure: #GClosure to decrement the reference count on
*
* Decrements the reference count of a closure after it was previously
* incremented by the same caller. If no other callers are using the closure,
* then the closure will be destroyed and freed.
*
* Decrements the reference count of a closure after it was previously
* incremented by the same caller. If no other callers are using the
* closure, then the closure will be destroyed and freed.
*/
void
g_closure_unref (GClosure *closure)
@@ -594,27 +603,28 @@ g_closure_unref (GClosure *closure)
/**
* g_closure_sink:
* @closure: #GClosure to decrement the initial reference count on, if it's
* still being held
*
* Takes over the initial ownership of a closure.
* Each closure is initially created in a <firstterm>floating</firstterm> state,
* which means that the initial reference count is not owned by any caller.
* g_closure_sink() checks to see if the object is still floating, and if so,
* unsets the floating state and decreases the reference count. If the closure
* is not floating, g_closure_sink() does nothing. The reason for the existance
* of the floating state is to prevent cumbersome code sequences like:
* still being held
*
* Takes over the initial ownership of a closure. Each closure is
* initially created in a <firstterm>floating</firstterm> state, which
* means that the initial reference count is not owned by any caller.
* g_closure_sink() checks to see if the object is still floating, and
* if so, unsets the floating state and decreases the reference
* count. If the closure is not floating, g_closure_sink() does
* nothing. The reason for the existance of the floating state is to
* prevent cumbersome code sequences like:
* |[
* closure = g_cclosure_new (cb_func, cb_data);
* g_source_set_closure (source, closure);
* closure = g_cclosure_new (cb_func, cb_data);
* g_source_set_closure (source, closure);
* g_closure_unref (closure); // XXX GObject doesn't really need this
* ]|
* Because g_source_set_closure() (and similar functions) take ownership of the
* initial reference count, if it is unowned, we instead can write:
* Because g_source_set_closure() (and similar functions) take ownership of the
* initial reference count, if it is unowned, we instead can write:
* |[
* g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
* ]|
*
* Generally, this function is used together with g_closure_ref(). Ane example
*
* Generally, this function is used together with g_closure_ref(). Ane example
* of storing a closure for later notification looks like:
* |[
* static GClosure *notify_closure = NULL;
@@ -631,7 +641,7 @@ g_closure_unref (GClosure *closure)
* }
* }
* ]|
*
*
* Because g_closure_sink() may decrement the reference count of a closure
* (if it hasn't been called on @closure yet) just like g_closure_unref(),
* g_closure_ref() should be called prior to this function.
@@ -661,12 +671,11 @@ g_closure_sink (GClosure *closure)
* g_closure_remove_invalidate_notifier:
* @closure: a #GClosure
* @notify_data: data which was passed to g_closure_add_invalidate_notifier()
* when registering @notify_func
* when registering @notify_func
* @notify_func: the callback function to remove
*
*
* Removes an invalidation notifier.
*
*
*
* Notice that notifiers are automatically removed after they are run.
*/
void
@@ -692,9 +701,9 @@ g_closure_remove_invalidate_notifier (GClosure *closure,
* @notify_data: data which was passed to g_closure_add_finalize_notifier()
* when registering @notify_func
* @notify_func: the callback function to remove
*
*
* Removes a finalization notifier.
*
*
* Notice that notifiers are automatically removed after they are run.
*/
void
@@ -718,12 +727,12 @@ g_closure_remove_finalize_notifier (GClosure *closure,
* g_closure_invoke:
* @closure: a #GClosure
* @return_value: a #GValue to store the return value. May be %NULL if the
* callback of @closure doesn't return a value.
* callback of @closure doesn't return a value.
* @n_param_values: the length of the @param_values array
* @param_values: an array of #GValue<!-- -->s holding the arguments on
* which to invoke the callback of @closure
* which to invoke the callback of @closure
* @invocation_hint: a context-dependent invocation hint
*
*
* Invokes the closure, i.e. executes the callback represented by the @closure.
*/
void
@@ -773,7 +782,7 @@ g_closure_invoke (GClosure *closure,
* g_closure_set_marshal:
* @closure: a #GClosure
* @marshal: a #GClosureMarshal function
*
*
* Sets the marshaller of @closure. The <literal>marshal_data</literal>
* of @marshal provides a way for a meta marshaller to provide additional
* information to the marshaller. (See g_closure_set_meta_marshal().) For
@@ -800,10 +809,10 @@ g_closure_set_marshal (GClosure *closure,
* @callback_func: the function to invoke
* @user_data: user data to pass to @callback_func
* @destroy_data: destroy notify to be called when @user_data is no longer used
*
* Creates a new closure which invokes @callback_func with @user_data as
* the last parameter.
*
*
* Creates a new closure which invokes @callback_func with @user_data as
* the last parameter.
*
* Returns: a new #GCClosure
*/
GClosure*
@@ -828,10 +837,10 @@ g_cclosure_new (GCallback callback_func,
* @callback_func: the function to invoke
* @user_data: user data to pass to @callback_func
* @destroy_data: destroy notify to be called when @user_data is no longer used
*
* Creates a new closure which invokes @callback_func with @user_data as
* the first parameter.
*
*
* Creates a new closure which invokes @callback_func with @user_data as
* the first parameter.
*
* Returns: a new #GCClosure
*/
GClosure*
@@ -901,13 +910,13 @@ g_type_iface_meta_marshal (GClosure *closure,
/**
* g_signal_type_cclosure_new:
* @itype: the #GType identifier of an interface or classed type
* @struct_offset: the offset of the member function of @itype's class
* @struct_offset: the offset of the member function of @itype's class
* structure which is to be invoked by the new closure
*
*
* Creates a new closure which invokes the function found at the offset
* @struct_offset in the class structure of the interface or classed type
* identified by @itype.
*
*
* Returns: a new #GCClosure
*/
GClosure*
@@ -938,10 +947,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__BOOLEAN:
* @closure: the #GClosure to which the marshaller belongs
@@ -951,10 +961,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__CHAR:
* @closure: the #GClosure to which the marshaller belongs
@@ -964,10 +975,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__UCHAR:
* @closure: the #GClosure to which the marshaller belongs
@@ -977,10 +989,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__INT:
* @closure: the #GClosure to which the marshaller belongs
@@ -990,10 +1003,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__UINT:
* @closure: the #GClosure to which the marshaller belongs
@@ -1003,10 +1017,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__LONG:
* @closure: the #GClosure to which the marshaller belongs
@@ -1016,10 +1031,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__ULONG:
* @closure: the #GClosure to which the marshaller belongs
@@ -1029,10 +1045,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__ENUM:
* @closure: the #GClosure to which the marshaller belongs
@@ -1042,10 +1059,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type..
*/
/**
* g_cclosure_marshal_VOID__FLAGS:
* @closure: the #GClosure to which the marshaller belongs
@@ -1055,10 +1073,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type.
*/
/**
* g_cclosure_marshal_VOID__FLOAT:
* @closure: the #GClosure to which the marshaller belongs
@@ -1068,10 +1087,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__DOUBLE:
* @closure: the #GClosure to which the marshaller belongs
@@ -1081,10 +1101,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__STRING:
* @closure: the #GClosure to which the marshaller belongs
@@ -1094,10 +1115,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__PARAM:
* @closure: the #GClosure to which the marshaller belongs
@@ -1107,10 +1129,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__BOXED:
* @closure: the #GClosure to which the marshaller belongs
@@ -1120,10 +1143,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__POINTER:
* @closure: the #GClosure to which the marshaller belongs
@@ -1133,10 +1157,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__OBJECT:
* @closure: the #GClosure to which the marshaller belongs
@@ -1146,10 +1171,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__UINT_POINTER:
* @closure: the #GClosure to which the marshaller belongs
@@ -1159,10 +1185,11 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_BOOLEAN__FLAGS:
* @closure: the #GClosure to which the marshaller belongs
@@ -1172,14 +1199,15 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
* denotes a flags type.
*/
/**
* g_cclosure_marshal_BOOL__FLAGS:
*
*
* Another name for g_cclosure_marshal_BOOLEAN__FLAGS().
*/
/**
@@ -1191,7 +1219,7 @@ g_signal_type_cclosure_new (GType itype,
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
*
* A marshaller for a #GCClosure with a callback of type
* <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>.
*/