Fix up section comments

svn path=/trunk/; revision=7137

gobject/ChangeLog

@@ -1,3 +1,7 @@
+2008-07-01  Matthias Clasen  <mclasen@redhat.com>
+
+	* *.c: Fix up section comments far enough to avoid regressions.
+
 2008-06-27  Hans Breuer  <hans@breuer.org>
 
 	* glib-genmarshal.c : move G_OS_WIN32 inclusion of <io.h> down to

gobject/gboxed.c

@@ -32,13 +32,10 @@
 
 /**
  * SECTION:gboxed
- *
+ * @short_description: A mechanism to wrap opaque C structures registered
- * @Short_description: A mechanism to wrap opaque C structures registered
+ *     by the type system
- * by the type system
+ * @see_also: #GParamSpecBoxed, g_param_spec_boxed()
- *
+ * @title: Boxed Types
- * @See_also: #GParamSpecBoxed, g_param_spec_boxed()
- *
- * @Title: Boxed Types
  *
  * GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
  * thing the type system needs to know about the structures is how to copy and

gobject/gclosure.c

@@ -33,10 +33,8 @@
 
 /**
  * SECTION:gclosure
- *
+ * @short_description: Functions as first-class objects
- * @Short_description: Functions as first-class objects
+ * @title: Closures
- *
- * @Title: Closures
  *
  * A #GClosure represents a callback supplied by the programmer. It
  * will generally comprise a function of some kind and a marshaller

gobject/genums.c

@@ -33,14 +33,12 @@
 
 /**
  * SECTION:enumerations_flags
- *
+ * @short_description: Enumeration and flags types
- * @Short_description: Enumeration and flags types
+ * @see_also:#GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(),
- *
- * @See_also:#GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(),
  * g_param_spec_flags(),
  *
  * <link linkend="glib-mkenums">glib-mkenums</link>
- * @Title: Enumeration and Flag Types
+ * @title: Enumeration and Flag Types
  *
  * The GLib type system provides fundamental types for enumeration and
  * flags types. (Flags types are like enumerations, but allow their

gobject/gobject.c

@@ -41,12 +41,9 @@
 
 /**
  * SECTION:objects
- *
+ * @short_description: The base object type
- * @Short_description: The base object type
+ * @see_also: #GParamSpecObject, g_param_spec_object()
- *
+ * @title: The Base Object Type
- * @See_also:#GParamSpecObject, g_param_spec_object()
- *
- * @Title: The Base Object Type
  *
  * GObject is the fundamental type providing the common attributes and
  * methods for all object types in GTK+, Pango and other libraries

gobject/gparam.c

@@ -33,14 +33,11 @@
 
 /**
  * SECTION:gparamspec
- *
+ * @short_description: Metadata for parameter specifications
- * @Short_description: Metadata for parameter specifications
+ * @see_also: g_object_class_install_property(), g_object_set(),
- *
+ *     g_object_get(), g_object_set_property(), g_object_get_property(),
- * @See_also:g_object_class_install_property(), g_object_set(),
+ *     g_value_register_transform_func()
- * g_object_get(), g_object_set_property(), g_object_get_property(),
+ * @title: GParamSpec
- * g_value_register_transform_func()
- *
- * @Title: GParamSpec
  *
  * #GParamSpec is an object structure that encapsulates the metadata
  * required to specify parameters, such as e.g. #GObject properties.

gobject/gparamspecs.c

@@ -33,12 +33,9 @@
 
 /**
  * SECTION:param_value_types
- *
+ * @short_description: Standard Parameter and Value Types
- * @Short_description: Standard Parameter and Value Types
+ * @see_also: #GParamSpec, #GValue, g_object_class_install_property().
- *
+ * @title: Parameters and Values
- * @See_also: #GParamSpec, #GValue, g_object_class_install_property().
- *
- * @Title: Parameters and Values
  *
  * #GValue provides an abstract container structure which can be
  * copied, transformed and compared while holding a value of any

gobject/gsignal.c

@@ -41,11 +41,9 @@
 
 /**
  * SECTION:signals
- *
+ * @short_description: A means for customization of object behaviour
- * @Short_description: A means for customization of object behaviour
+ *     and a general purpose notification mechanism
- * and a general purpose notification mechanism
+ * @title: Signals
- *
- * @Title: Signals
  *
  * The basic concept of the signal system is that of the
  * <emphasis>emission</emphasis> of a signal. Signals are introduced
@@ -54,10 +52,11 @@
  * basically they are a per-type facility that is inherited.  A signal
  * emission mainly involves invocation of a certain set of callbacks
  * in precisely defined manner. There are two main categories of such
- * callbacks, per-object i'm referring to those types as "object
+ * callbacks, per-object 
- * types" in the following, simply because that is the context most
+ * <footnote><para>Although signals can deal with any kind of instantiatable 
- * users will encounter signals in.
+ * type, i'm referring to those types as "object types" in the following, 
- *
+ * simply because that is the context most users will encounter signals in.
+ * </para></footnote>
  * ones and user provided ones.
  * The per-object callbacks are most often referred to as "object method
  * handler" or "default (signal) handler", while user provided callbacks are

gobject/gtype.c

@@ -34,11 +34,9 @@
 
 /**
  * SECTION:gtype
- *
+ * @short_description: The GLib Runtime type identification and
- * @Short_description: The GLib Runtime type identification and
+ *     management system
- * management system
+ * @title:Type Information
- *
- * @Title:Type Information
  *
  * The GType API is the foundation of the GObject system.  It provides the
  * facilities for registering and managing all fundamental data types,

gobject/gtypemodule.c

@@ -28,10 +28,8 @@
 
 /**
  * SECTION:gtypemodule
- *
+ * @short_description: Type loading modules
- * @Short_description: Type loading modules
+ * @see_also:<variablelist>
- *
- * @See_also:<variablelist>
  * <varlistentry>
  * <term>#GTypePlugin</term>
  * <listitem><para>The abstract type loader interface.</para></listitem>
@@ -41,8 +39,7 @@
  * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
  * </varlistentry>
  * </variablelist>
- *
+ * @title: GTypeModule
- * @Title: GTypeModule
  *
  * #GTypeModule provides a simple implementation of the #GTypePlugin
  * interface. The model of #GTypeModule is a dynamically loaded module

gobject/gtypeplugin.c

@@ -25,12 +25,9 @@
 
 /**
  * SECTION:gtypeplugin
- *
+ * @short_description: An interface for dynamically loadable types
- * @Short_description: An interface for dynamically loadable types
+ * @see_also: #GTypeModule and g_type_register_dynamic().
- *
+ * @title: GTypePlugin
- * @See_also:#GTypeModule and g_type_register_dynamic().
- *
- * @Titile: GTypePlugin
  *
  * The GObject type system supports dynamic loading of types. The
  * #GTypePlugin interface is used to handle the lifecycle of

gobject/gvalue.c

@@ -33,17 +33,14 @@
 
 /**
  * SECTION:generic_values
- *
+ * @short_description: A polymorphic type that can hold values of any
- * @Short_description: A polymorphic type that can hold values of any
+ *     other type
- * other type
+ * @see_also: The fundamental types which all support #GValue
- *
+ *     operations and thus can be used as a type initializer for
- * @See_also: The fundamental types which all support #GValue
+ *     g_value_init() are defined by a separate interface.  See the <link
- * operations and thus can be used as a type initializer for
+ *     linkend="gobject-Standard-Parameter-and-Value-Types">Standard
- * g_value_init() are defined by a separate interface.  See the <link
+ *     Values API</link> for details.
- * linkend="gobject-Standard-Parameter-and-Value-Types">Standard
+ * @title: Generic values
- * Values API</link> for details.
- *
- * @Title: Generic values
  *
  * The #GValue structure is basically a variable container that consists
  * of a type identifier and a specific value of that type.

gobject/gvaluearray.c

@@ -32,13 +32,10 @@
 
 /**
  * SECTION:value_arrays
- *
+ * @short_description: A container structure to maintain an array of
- * @Short_description: A container structure to maintain an array of
+ *     generic values
- * generic values
+ * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array()
- *
+ * @title: Value arrays
- * @See_also:#GValue, #GParamSpecValueArray, g_param_spec_value_array()
- *
- * @Title: Value arrays
  *
  * The prime purpose of a #GValueArray is for it to be used as an
  * object property that holds an array of values. A #GValueArray wraps