docs: fix many documentation issues in gobject/

docs/reference/gobject/Makefile.am

@@ -25,10 +25,9 @@ CFILE_GLOB=$(top_srcdir)/gobject/*.c
 # Headers to ignore
 IGNORE_HFILES = \
 	tests			\
+	gatomicarray.h		\
 	gobject_trace.h		\
-	gtype-private.h		\
-	gatomicarray.h
-
+	gtype-private.h
 
 # CFLAGS and LDFLAGS for compiling scan program. Only needed
 # if $(DOC_MODULE).types is non-empty.

docs/reference/gobject/gobject-sections.txt

@@ -425,6 +425,10 @@ g_source_get_type
 g_pollfd_get_type
 g_bytes_get_type
 g_key_file_get_type
+g_checksum_get_type
+g_mapped_file_get_type
+g_markup_parse_context_get_type
+g_thread_get_type
 </SECTION>
 
 <SECTION>
@@ -492,7 +496,6 @@ G_PARAM_SPEC_VALUE_TYPE
 GParamSpec
 GParamSpecClass
 GParamFlags
-G_PARAM_READWRITE
 G_PARAM_STATIC_STRINGS
 G_PARAM_MASK
 G_PARAM_USER_SHIFT

gobject/gboxed.c

@@ -184,12 +184,6 @@ g_strv_get_type (void)
   return g_define_type_id__volatile;
 }
 
-/**
- * g_variant_get_gtype:
- *
- * Since: 2.24
- * Deprecated: 2.26
- */
 GType
 g_variant_get_gtype (void)
 {

gobject/gclosure.c

@@ -1451,6 +1451,26 @@ g_cclosure_marshal_generic (GClosure     *closure,
     value_from_ffi_type (return_gvalue, rvalue);
 }
 
+/**
+ * g_cclosure_marshal_generic_va:
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: (allow-none): a #GValue to store the return
+ *  value. May be %NULL if the callback of @closure doesn't return a
+ *  value.
+ * @instance: the instance on which the closure is invoked.
+ * @args_list: va_list of arguments to be passed to the closure.
+ * @marshal_data: (allow-none): additional data specified when
+ *  registering the marshaller, see g_closure_set_marshal() and
+ *  g_closure_set_meta_marshal()
+ * @n_params: the length of the @param_types array
+ * @param_types: (array length=n_params): the #GType of each argument from
+ *  @args_list.
+ *
+ * A generic #GVaClosureMarshal function implemented via
+ * [libffi](http://sourceware.org/libffi/).
+ *
+ * Since: 2.30
+ */
 void
 g_cclosure_marshal_generic_va (GClosure *closure,
 			       GValue   *return_value,

gobject/gclosure.h

@@ -119,6 +119,25 @@ typedef void  (*GClosureMarshal)	(GClosure	*closure,
 					 gpointer        invocation_hint,
 					 gpointer	 marshal_data);
 
+/**
+ * GVaClosureMarshal:
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: (allow-none): a #GValue to store the return
+ *  value. May be %NULL if the callback of @closure doesn't return a
+ *  value.
+ * @instance: the instance on which the closure is invoked.
+ * @args: va_list of arguments to be passed to the closure.
+ * @marshal_data: (allow-none): additional data specified when
+ *  registering the marshaller, see g_closure_set_marshal() and
+ *  g_closure_set_meta_marshal()
+ * @n_params: the length of the @param_types array
+ * @param_types: (array length=n_params): the #GType of each argument from
+ *  @args.
+ *
+ * This is the signature of va_list marshaller functions, an optional
+ * marshaller that can be used in some situations to avoid
+ * marshalling the signal argument into GValues.
+ */
 typedef void (* GVaClosureMarshal) (GClosure *closure,
 				    GValue   *return_value,
 				    gpointer  instance,

gobject/gparam.c

@@ -1523,7 +1523,7 @@ g_value_dup_param (const GValue *value)
 }
 
 /**
- * g_param_get_default_value:
+ * g_param_spec_get_default_value:
  * @param: a #GParamSpec
  *
  * Gets the default value of @param as a pointer to a #GValue.

gobject/gparam.h

@@ -165,6 +165,7 @@ typedef enum
   G_PARAM_EXPLICIT_NOTIFY     = 1 << 30,
   G_PARAM_DEPRECATED          = 1 << 31
 } GParamFlags;
+
 /**
  * G_PARAM_STATIC_STRINGS:
  * 

gobject/gsignal.c

@@ -1733,6 +1733,19 @@ g_signal_newv (const gchar       *signal_name,
   return signal_id;
 }
 
+/**
+ * g_signal_set_va_marshaller:
+ * @signal_id: the signal id
+ * @instance_type: the instance type on which to set the marshaller.
+ * @va_marshaller: the marshaller to set.
+ *
+ * Change the #GSignalCVaMarshaller used for a given signal.  This is a
+ * specialised form of the marshaller that can often be used for the
+ * common case of a single connected signal handler and avoids the
+ * overhead of #GValue.  Its use is optional.
+ *
+ * Since: 2.32
+ */
 void
 g_signal_set_va_marshaller (guint              signal_id,
 			    GType              instance_type,

gobject/gtype.h

@@ -1114,12 +1114,10 @@ struct _GInterfaceInfo
  *  this value bit-by-bit. Each character in the format represents
  *  an argument to be collected, and the characters themselves indicate
  *  the type of the argument. Currently supported arguments are:
- *
  *  - 'i' - Integers. passed as collect_values[].v_int.
  *  - 'l' - Longs. passed as collect_values[].v_long.
  *  - 'd' - Doubles. passed as collect_values[].v_double.
  *  - 'p' - Pointers. passed as collect_values[].v_pointer.
- *
  *  It should be noted that for variable argument list construction,
  *  ANSI C promotes every type smaller than an integer to an int, and
  *  floats to doubles. So for collection of short int or char, 'i'

gobject/gtypemodule.h

@@ -240,6 +240,20 @@ type_name##_register_type (GTypeModule *type_module) \
   g_type_module_add_interface (type_module, g_define_type_id, TYPE_IFACE, &g_implement_interface_info); \
 }
 
+/**
+ * G_ADD_PRIVATE_DYNAMIC:
+ * @TypeName: the name of the type in CamelCase
+ *
+ * A convenience macro to ease adding private data to instances of a new dynamic
+ * type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See
+ * G_ADD_PRIVATE() for details, it is similar but for static types.
+ *
+ * Note that this macro can only be used together with the
+ * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
+ * names from that macro.
+ *
+ * Since: 2.38
+ */
 #define G_ADD_PRIVATE_DYNAMIC(TypeName)         { \
   TypeName##_private_offset = sizeof (TypeName##Private); \
 }

gobject/gvaluecollector.h

@@ -156,6 +156,13 @@ G_STMT_START {										\
   G_VALUE_COLLECT_INIT(value, _value_type, var_args, flags, __error);			\
 } G_STMT_END
 
+/**
+ * G_VALUE_COLLECT_SKIP:
+ * @_value_type: the #GType of the value to skip
+ * @var_args: the va_list variable; it may be evaluated multiple times
+ *
+ * Skip an argument of type @_value_type from @var_args.
+ */
 #define G_VALUE_COLLECT_SKIP(_value_type, var_args)					\
 G_STMT_START {										\
   GTypeValueTable *_vtable = g_type_value_table_peek (_value_type);			\