From 8009afe73d57caf99bed826c44184e4b35096c10 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Mon, 25 Sep 2023 15:17:25 -0400
Subject: [PATCH] docs: Move the GParamSpec SECTION

Move the content to the struct docs. Also drop the paramspecs SECTION,
as it was largely duplicated information.

Helps: #3037
---
 gobject/gparam.c      | 22 ++++++++++------------
 gobject/gparam.h      | 12 +-----------
 gobject/gparamspecs.c | 23 -----------------------
 3 files changed, 11 insertions(+), 46 deletions(-)

diff --git a/gobject/gparam.c b/gobject/gparam.c
index e067d6026..450e6040b 100644
--- a/gobject/gparam.c
+++ b/gobject/gparam.c
@@ -31,29 +31,27 @@
 #include "gtype-private.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: (ref-func g_param_spec_ref_sink) (unref-func g_param_spec_unref) (set-value-func g_value_set_param) (get-value-func g_value_get_param)
+ * @g_type_instance: private `GTypeInstance` portion
+ * @name: name of this parameter: always an interned string
+ * @flags: `GParamFlags` flags for this parameter
+ * @value_type: the `GValue` type for this parameter
+ * @owner_type: `GType` type that uses (introduces) this parameter
  *
- * #GParamSpec is an object structure that encapsulates the metadata
- * required to specify parameters, such as e.g. #GObject properties.
+ * `GParamSpec` encapsulates the metadata required to specify parameters, such as `GObject` properties.
  *
- * ## Parameter names # {#canonical-parameter-names}
+ * ## Parameter names
  *
  * A property name consists of one or more segments consisting of ASCII letters
  * and digits, separated by either the `-` or `_` character. The first
  * character of a property name must be a letter. These are the same rules as
- * for signal naming (see g_signal_new()).
+ * for signal naming (see [func@GObject.signal_new]).
  *
- * When creating and looking up a #GParamSpec, either separator can be
+ * When creating and looking up a `GParamSpec`, either separator can be
  * used, but they cannot be mixed. Using `-` is considerably more
  * efficient, and is the ‘canonical form’. Using `_` is discouraged.
  */
 
-
 /* --- defines --- */
 #define PARAM_FLOATING_FLAG                     0x2
 #define	G_PARAM_USER_MASK			(~0U << G_PARAM_USER_SHIFT)
diff --git a/gobject/gparam.h b/gobject/gparam.h
index 6454e69a9..506a9c2cd 100644
--- a/gobject/gparam.h
+++ b/gobject/gparam.h
@@ -203,17 +203,7 @@ typedef struct _GParamSpec      GParamSpec;
 typedef struct _GParamSpecClass GParamSpecClass;
 typedef struct _GParameter	GParameter GOBJECT_DEPRECATED_TYPE_IN_2_54;
 typedef struct _GParamSpecPool  GParamSpecPool;
-/**
- * GParamSpec: (ref-func g_param_spec_ref_sink) (unref-func g_param_spec_unref) (set-value-func g_value_set_param) (get-value-func g_value_get_param)
- * @g_type_instance: private #GTypeInstance portion
- * @name: name of this parameter: always an interned string
- * @flags: #GParamFlags flags for this parameter
- * @value_type: the #GValue type for this parameter
- * @owner_type: #GType type that uses (introduces) this parameter
- * 
- * All other fields of the GParamSpec struct are private and
- * should not be used directly.
- */
+
 struct _GParamSpec
 {
   GTypeInstance  g_type_instance;
diff --git a/gobject/gparamspecs.c b/gobject/gparamspecs.c
index 17b860657..5db328155 100644
--- a/gobject/gparamspecs.c
+++ b/gobject/gparamspecs.c
@@ -37,29 +37,6 @@
 #include "gvaluearray.h"
 
 
-/**
- * SECTION:param_value_types
- * @short_description: Standard Parameter and Value Types
- * @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
- * (derived) type, which is registered as a #GType with a
- * #GTypeValueTable in its #GTypeInfo structure.  Parameter
- * specifications for most value types can be created as #GParamSpec
- * derived instances, to implement e.g. #GObject properties which
- * operate on #GValue containers.
- *
- * 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.
- *
- * See also #GValue for more information.
- *
- */
-
-
 #define	G_FLOAT_EPSILON		(1e-30)
 #define	G_DOUBLE_EPSILON	(1e-90)