GNOME.org
 

[glib] docs: fix many documentation issues in gobject/

commit 6a97275c4507e08b66fdeb4bb054bb8f78096f14
Author: Xavier Claessens <xavier claessens collabora com>
Date:   Thu Feb 5 15:24:27 2015 +0100

    docs: fix many documentation issues in gobject/

 docs/reference/gobject/Makefile.am          |    5 ++---
 docs/reference/gobject/gobject-sections.txt |    5 ++++-
 gobject/gboxed.c                            |    6 ------
 gobject/gclosure.c                          |   20 ++++++++++++++++++++
 gobject/gclosure.h                          |   19 +++++++++++++++++++
 gobject/gparam.c                            |    2 +-
 gobject/gparam.h                            |    1 +
 gobject/gsignal.c                           |   13 +++++++++++++
 gobject/gtype.h                             |    2 --
 gobject/gtypemodule.h                       |   14 ++++++++++++++
 gobject/gvaluecollector.h                   |    7 +++++++
 11 files changed, 81 insertions(+), 13 deletions(-)
---
diff --git a/docs/reference/gobject/Makefile.am b/docs/reference/gobject/Makefile.am
index beff782..1ca6158 100644
--- a/docs/reference/gobject/Makefile.am
+++ b/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.
diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt
index e47664a..fe322d6 100644
--- a/docs/reference/gobject/gobject-sections.txt
+++ b/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
diff --git a/gobject/gboxed.c b/gobject/gboxed.c
index ab41951..ca7f66c 100644
--- a/gobject/gboxed.c
+++ b/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)
 {
diff --git a/gobject/gclosure.c b/gobject/gclosure.c
index 8d0d656..33353bb 100644
--- a/gobject/gclosure.c
+++ b/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,
diff --git a/gobject/gclosure.h b/gobject/gclosure.h
index 1cc609e..41f0799 100644
--- a/gobject/gclosure.h
+++ b/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,
diff --git a/gobject/gparam.c b/gobject/gparam.c
index c69ee02..677f16c 100644
--- a/gobject/gparam.c
+++ b/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.
diff --git a/gobject/gparam.h b/gobject/gparam.h
index 6e2242d..88b18fd 100644
--- a/gobject/gparam.h
+++ b/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:
  * 
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index 257fc8d..e02a700 100644
--- a/gobject/gsignal.c
+++ b/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,
diff --git a/gobject/gtype.h b/gobject/gtype.h
index 292678b..c2624f6 100644
--- a/gobject/gtype.h
+++ b/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'
diff --git a/gobject/gtypemodule.h b/gobject/gtypemodule.h
index e4cae1a..9c63bac 100644
--- a/gobject/gtypemodule.h
+++ b/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); \
 }
diff --git a/gobject/gvaluecollector.h b/gobject/gvaluecollector.h
index 11a1ad8..e668394 100644
--- a/gobject/gvaluecollector.h
+++ b/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);                    \
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]