moved includes back to the top of the files (before gtk-doc SECTION

[platform/upstream/glib.git] / gobject / gparam.c

diff --git a/gobject/gparam.c b/gobject/gparam.c
index 544f431..e9b1292 100644 (file)
--- a/gobject/gparam.c
+++ b/gobject/gparam.c
@@ -16,34 +16,39 @@
  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+
+/*
+ * MT safe
+ */
+
+#include "config.h"
+
+#include <string.h>
+
+#include "gparam.h"
+#include "gparamspecs.h"
+#include "gvaluecollector.h"
+#include "gobjectalias.h"
+
+
 /**
  * SECTION:gparamspec
  * @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(), 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.
- * 
+ *
  * <para id="canonical-parameter-name">
  * Parameter names need to start with a letter (a-z or A-Z). Subsequent
  * characters can be letters, numbers or a '-'.
  * All other characters are replaced by a '-' during construction.
  * The result of this replacement is called the canonical name of the
  * parameter.
+ * </para>
  */
-/*
- * MT safe
- */
-
-#include       "gparam.h"
-#include        "gparamspecs.h"
-
-#include       "gvaluecollector.h"
-#include       "gobjectalias.h"
-#include       <string.h>
-
 
 
 /* --- defines --- */
@@ -1385,6 +1390,13 @@ g_param_type_register_static (const gchar              *name,
   return g_type_register_static (G_TYPE_PARAM, name, &info, 0);
 }
 
+/**
+ * g_value_set_param:
+ * @value: a valid #GValue of type %G_TYPE_PARAM
+ * @param: the #GParamSpec to be set
+ * 
+ * Set the contents of a %G_TYPE_PARAM #GValue to @param.
+ */
 void
 g_value_set_param (GValue     *value,
                   GParamSpec *param)
@@ -1400,6 +1412,15 @@ g_value_set_param (GValue     *value,
     g_param_spec_ref (value->data[0].v_pointer);
 }
 
+/**
+ * g_value_set_param_take_ownership:
+ * @value: a valid #GValue of type %G_TYPE_PARAM
+ * @param: the #GParamSpec to be set
+ * 
+ * This is an internal function introduced mainly for C marshallers.
+ * 
+ * Deprecated: 2.4: Use g_value_take_param() instead.
+ */
 void
 g_value_set_param_take_ownership (GValue     *value,
                                  GParamSpec *param)
@@ -1407,6 +1428,17 @@ g_value_set_param_take_ownership (GValue     *value,
   g_value_take_param (value, param);
 }
 
+/**
+ * g_value_take_param:
+ * @value: a valid #GValue of type %G_TYPE_PARAM
+ * @param: the #GParamSpec to be set
+ * 
+ * Sets the contents of a %G_TYPE_PARAM #GValue to @param and
+ * takes over the ownership of the callers reference to @param; 
+ * the caller doesn't have to unref it any more.
+ * 
+ * Since: 2.4
+ */
 void
 g_value_take_param (GValue     *value,
                    GParamSpec *param)
@@ -1420,6 +1452,14 @@ g_value_take_param (GValue     *value,
   value->data[0].v_pointer = param; /* we take over the reference count */
 }
 
+/**
+ * g_value_get_param:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
+ * 
+ * Get the contents of a %G_TYPE_PARAM #GValue.
+ * 
+ * Returns: #GParamSpec content of @value
+ */
 GParamSpec*
 g_value_get_param (const GValue *value)
 {
@@ -1428,6 +1468,14 @@ g_value_get_param (const GValue *value)
   return value->data[0].v_pointer;
 }
 
+/**
+ * g_value_dup_param:
+ * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM
+ * 
+ * Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count.
+ * 
+ * Returns: #GParamSpec content of @value, should be unreferenced when no longer needed.
+ */
 GParamSpec*
 g_value_dup_param (const GValue *value)
 {