diff options
Diffstat (limited to 'girepository')
43 files changed, 1018 insertions, 449 deletions
diff --git a/girepository/docs.c b/girepository/docs.c new file mode 100644 index 00000000..a4798c41 --- /dev/null +++ b/girepository/docs.c @@ -0,0 +1,33 @@ +/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- + * GObject introspection: Dump introspection data + * + * Copyright (C) 2013 Dieter Verfaillie <dieterv@optionexplicit.be> + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the + * Free Software Foundation, Inc., 59 Temple Place - Suite 330, + * Boston, MA 02111-1307, USA. + */ + +/* This file collects documentation for macros, typedefs and + * the like, which have no good home in any of the 'real' source + * files. + */ + +/** + * SECTION:gicommontypes + * @title: common types + * @short_description: TODO + * + * TODO + */ diff --git a/girepository/giarginfo.c b/girepository/giarginfo.c index d61f4be2..572839c3 100644 --- a/girepository/giarginfo.c +++ b/girepository/giarginfo.c @@ -26,12 +26,12 @@ #include "girepository-private.h" -/* GIArgInfo function */ +/* GIArgInfo functions */ /** * SECTION:giarginfo - * @Short_description: Struct representing an argument - * @Title: GIArgInfo + * @title: GIArgInfo + * @short_description: Struct representing an argument * * GIArgInfo represents an argument. An argument is always * part of a #GICallableInfo. @@ -293,8 +293,9 @@ g_arg_info_get_destroy (GIArgInfo *info) * * Obtain the type information for @info. * - * Returns: (transfer full): the #GIArgInfo, free it with - * g_base_info_unref() when done. + * Returns: (transfer full): the #GITypeInfo holding the type + * information for @info, free it with g_base_info_unref() + * when done. */ GITypeInfo * g_arg_info_get_type (GIArgInfo *info) diff --git a/girepository/giarginfo.h b/girepository/giarginfo.h index 3f4163e3..4045ab9c 100644 --- a/girepository/giarginfo.h +++ b/girepository/giarginfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_ARG_INFO + * @info: an info structure + * + * Checks if @info is a GIArgInfo. + */ #define GI_IS_ARG_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_ARG) diff --git a/girepository/gibaseinfo.c b/girepository/gibaseinfo.c index 37893e6c..4bbe850a 100644 --- a/girepository/gibaseinfo.c +++ b/girepository/gibaseinfo.c @@ -71,6 +71,17 @@ _g_info_new_full (GIInfoType type, return (GIBaseInfo*)info; } +/** + * g_info_new: + * @type: TODO + * @container: TODO + * @typelib: TODO + * @offset: TODO + * + * TODO + * + * Returns: TODO + */ GIBaseInfo * g_info_new (GIInfoType type, GIBaseInfo *container, @@ -169,8 +180,8 @@ _g_type_info_init (GIBaseInfo *info, /** * SECTION:gibaseinfo - * @Short_description: Base struct for all GITypelib structs - * @Title: GIBaseInfo + * @title: GIBaseInfo + * @short_description: Base struct for all GITypelib structs * * GIBaseInfo is the common base struct of all other *Info structs * accessible through the #GIRepository API. @@ -209,7 +220,6 @@ _g_type_info_init (GIBaseInfo *info, * +----<link linkend="gi-GITypeInfo">GITypeInfo</link> * </synopsis> * </refsect1> - * */ /** diff --git a/girepository/gibaseinfo.h b/girepository/gibaseinfo.h index 54c8ee4f..a49dd506 100644 --- a/girepository/gibaseinfo.h +++ b/girepository/gibaseinfo.h @@ -33,6 +33,11 @@ G_BEGIN_DECLS +/** + * GIBaseInfoStub: + * + * TODO + */ struct _GIBaseInfoStub { /* <private> */ gint32 dummy1; diff --git a/girepository/gicallableinfo.c b/girepository/gicallableinfo.c index 28c5950e..e69e3e9d 100644 --- a/girepository/gicallableinfo.c +++ b/girepository/gicallableinfo.c @@ -33,8 +33,8 @@ /** * SECTION:gicallableinfo - * @Short_description: Struct representing a callable - * @Title: GICallableInfo + * @title: GICallableInfo + * @short_description: Struct representing a callable * * GICallableInfo represents an entity which is callable. * Currently a function (#GIFunctionInfo), virtual function, @@ -85,9 +85,10 @@ signature_offset (GICallableInfo *info) * g_callable_info_can_throw_gerror: * @info: a #GICallableInfo * - * Returns: %TRUE if this #GICallableInfo can throw a #GError + * TODO * * Since: 1.34 + * Returns: %TRUE if this #GICallableInfo can throw a #GError */ gboolean g_callable_info_can_throw_gerror (GICallableInfo *info) @@ -128,6 +129,7 @@ g_callable_info_can_throw_gerror (GICallableInfo *info) * is one more C argument than is exposed by introspection: the "self" * or "this" object. * + * Returns: %TRUE if @info is a method, %FALSE otherwise * Since: 1.34 */ gboolean @@ -430,11 +432,17 @@ g_callable_info_iterate_return_attributes (GICallableInfo *info, return TRUE; } -/* Extract the correct bits from an ffi_arg return value into +/** + * gi_type_info_extract_ffi_return_value: + * @return_info: TODO + * @ffi_value: TODO + * @arg: (out caller-allocates): TODO + * + * Extract the correct bits from an ffi_arg return value into * GIArgument: https://bugzilla.gnome.org/show_bug.cgi?id=665152 * - * Also see the ffi_call man page - the storage requirements for return - * values are "special". + * Also see <citerefentry><refentrytitle>ffi_call</refentrytitle><manvolnum>3</manvolnum></citerefentry> + * - the storage requirements for return values are "special". */ void gi_type_info_extract_ffi_return_value (GITypeInfo *return_info, @@ -501,6 +509,21 @@ gi_type_info_extract_ffi_return_value (GITypeInfo *return_info, } } +/** + * g_callable_info_invoke: + * @info: TODO + * @function: TODO + * @in_args: TODO + * @n_in_args: TODO + * @out_args: TODO + * @n_out_args: TODO + * @return_value: TODO + * @is_method: TODO + * @throws: TODO + * @error: TODO + * + * TODO + */ gboolean g_callable_info_invoke (GIFunctionInfo *info, gpointer function, diff --git a/girepository/gicallableinfo.h b/girepository/gicallableinfo.h index a7d7079a..71f9d0c6 100644 --- a/girepository/gicallableinfo.h +++ b/girepository/gicallableinfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_CALLABLE_INFO + * @info: an info structure + * + * Checks if @info is a #GICallableInfo or derived from it. + */ #define GI_IS_CALLABLE_INFO(info) \ ((g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FUNCTION) || \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_CALLBACK) || \ diff --git a/girepository/giconstantinfo.c b/girepository/giconstantinfo.c index 88220b4e..7b2f716c 100644 --- a/girepository/giconstantinfo.c +++ b/girepository/giconstantinfo.c @@ -29,8 +29,8 @@ /** * SECTION:giconstantinfo - * @Short_description: Struct representing a constant - * @Title: GIConstantInfo + * @title: GIConstantInfo + * @short_description: Struct representing a constant * * GIConstantInfo represents a constant. A constant has a type associated * which can be obtained by calling g_constant_info_get_type() and a value, diff --git a/girepository/giconstantinfo.h b/girepository/giconstantinfo.h index 2bbf9569..2ce1dcad 100644 --- a/girepository/giconstantinfo.h +++ b/girepository/giconstantinfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_CONSTANT_INFO + * @info: an info structure + * + * Checks if @info is a #GIConstantInfo. + */ #define GI_IS_CONSTANT_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_CONSTANT) diff --git a/girepository/gienuminfo.c b/girepository/gienuminfo.c index 400a56d6..253ec684 100644 --- a/girepository/gienuminfo.c +++ b/girepository/gienuminfo.c @@ -28,8 +28,8 @@ /** * SECTION:gienuminfo - * @Short_description: Structs representing an enumeration and its values - * @Title: GIEnumInfo + * @title: GIEnumInfo + * @short_description: Structs representing an enumeration and its values * * A GIEnumInfo represents an enumeration and a GIValueInfo struct represents a value * of an enumeration. The GIEnumInfo contains a set of values and a type @@ -46,13 +46,13 @@ */ /** -* g_enum_info_get_n_values: -* @info: a #GIEnumInfo -* -* Obtain the number of values this enumeration contains. -* -* Returns: the number of enumeration values -*/ + * g_enum_info_get_n_values: + * @info: a #GIEnumInfo + * + * Obtain the number of values this enumeration contains. + * + * Returns: the number of enumeration values + */ gint g_enum_info_get_n_values (GIEnumInfo *info) { @@ -76,7 +76,6 @@ g_enum_info_get_n_values (GIEnumInfo *info) * * Returns: (transfer none): the string form of the error domain associated * with this enum, or %NULL. - * * Since: 1.29.17 */ const gchar * @@ -131,7 +130,6 @@ g_enum_info_get_value (GIEnumInfo *info, * Obtain the number of methods that this enum type has. * * Returns: number of methods - * * Since: 1.29.17 */ gint @@ -157,7 +155,6 @@ g_enum_info_get_n_methods (GIEnumInfo *info) * * Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling * g_base_info_unref() when done. - * * Since: 1.29.17 */ GIFunctionInfo * @@ -189,12 +186,12 @@ g_enum_info_get_method (GIEnumInfo *info, * * Obtain the tag of the type used for the enum in the C ABI. This will * will be a signed or unsigned integral type. - + * * Note that in the current implementation the width of the type is * computed correctly, but the signed or unsigned nature of the type * may not match the sign of the type used by the C compiler. * - * Return Value: the storage type for the enumeration + * Returns: the storage type for the enumeration */ GITypeTag g_enum_info_get_storage_type (GIEnumInfo *info) diff --git a/girepository/gienuminfo.h b/girepository/gienuminfo.h index 0b9a9e1b..257e4c12 100644 --- a/girepository/gienuminfo.h +++ b/girepository/gienuminfo.h @@ -31,10 +31,22 @@ G_BEGIN_DECLS +/** + * GI_IS_ENUM_INFO + * @info: an info structure + * + * Checks if @info is a #GIEnumInfo. + */ #define GI_IS_ENUM_INFO(info) \ ((g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_ENUM) || \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FLAGS)) +/** + * GI_IS_VALUE_INFO + * @info: an info structure + * + * Checks if @info is a #GIValueInfo. + */ #define GI_IS_VALUE_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_VALUE) diff --git a/girepository/gifieldinfo.c b/girepository/gifieldinfo.c index 1d9a20dd..2bbc0214 100644 --- a/girepository/gifieldinfo.c +++ b/girepository/gifieldinfo.c @@ -29,13 +29,13 @@ /** * SECTION:gifieldinfo - * @Short_description: Struct representing a struct or union field - * @Title: GIFieldInfo + * @title: GIFieldInfo + * @short_description: Struct representing a struct or union field * * A GIFieldInfo struct represents a field of a struct (see #GIStructInfo), * union (see #GIUnionInfo) or an object (see #GIObjectInfo). The GIFieldInfo * is fetched by calling g_struct_info_get_field(), g_union_info_get_field() - * or g_object_info_get_value(). + * or g_object_info_get_field(). * A field has a size, type and a struct offset asssociated and a set of flags, * which is currently #GI_FIELD_IS_READABLE or #GI_FIELD_IS_WRITABLE. * @@ -167,7 +167,7 @@ g_field_info_get_type (GIFieldInfo *info) * @mem: pointer to a block of memory representing a C structure or union * @value: a #GIArgument into which to store the value retrieved * - * Reads a field identified by a #GFieldInfo from a C structure or + * Reads a field identified by a #GIFieldInfo from a C structure or * union. This only handles fields of simple C types. It will fail * for a field of a composite type like a nested structure or union * even if that is actually readable. @@ -355,7 +355,7 @@ g_field_info_get_field (GIFieldInfo *field_info, * @mem: pointer to a block of memory representing a C structure or union * @value: a #GIArgument holding the value to store * - * Writes a field identified by a #GFieldInfo to a C structure or + * Writes a field identified by a #GIFieldInfo to a C structure or * union. This only handles fields of simple C types. It will fail * for a field of a composite type like a nested structure or union * even if that is actually writable. Note also that that it will refuse diff --git a/girepository/gifieldinfo.h b/girepository/gifieldinfo.h index 4ca54093..56a2e22e 100644 --- a/girepository/gifieldinfo.h +++ b/girepository/gifieldinfo.h @@ -31,6 +31,13 @@ G_BEGIN_DECLS +/** + * GI_IS_FIELD_INFO + * @info: an info structure + * + * Checks if @info is a #GIFieldInfo. + * + */ #define GI_IS_FIELD_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FIELD) diff --git a/girepository/gifunctioninfo.c b/girepository/gifunctioninfo.c index a5858c76..ecd61275 100644 --- a/girepository/gifunctioninfo.c +++ b/girepository/gifunctioninfo.c @@ -30,8 +30,8 @@ /** * SECTION:gifunctioninfo - * @Short_description: Struct representing a function - * @Title: GIFunctionInfo + * @title: GIFunctionInfo + * @short_description: Struct representing a function * * GIFunctionInfo represents a function, method or constructor. * To find out what kind of entity a #GIFunctionInfo represents, call @@ -205,6 +205,13 @@ g_function_info_get_vfunc (GIFunctionInfo *info) return g_interface_info_get_vfunc (container, blob->index); } +/** + * g_invoke_error_quark: + * + * TODO + * + * Returns: TODO + */ GQuark g_invoke_error_quark (void) { diff --git a/girepository/gifunctioninfo.h b/girepository/gifunctioninfo.h index 7a9ecae0..7987c926 100644 --- a/girepository/gifunctioninfo.h +++ b/girepository/gifunctioninfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_FUNCTION_INFO + * @info: an info structure + * + * Checks if @info is a #GIFunctionInfo. + */ #define GI_IS_FUNCTION_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FUNCTION) @@ -39,6 +45,11 @@ GIFunctionInfoFlags g_function_info_get_flags (GIFunctionInfo *info); GIPropertyInfo * g_function_info_get_property (GIFunctionInfo *info); GIVFuncInfo * g_function_info_get_vfunc (GIFunctionInfo *info); +/** + * G_INVOKE_ERROR: + * + * TODO + */ #define G_INVOKE_ERROR (g_invoke_error_quark ()) GQuark g_invoke_error_quark (void); diff --git a/girepository/giinterfaceinfo.c b/girepository/giinterfaceinfo.c index f998da44..481fc54e 100644 --- a/girepository/giinterfaceinfo.c +++ b/girepository/giinterfaceinfo.c @@ -28,8 +28,8 @@ /** * SECTION:giinterfaceinfo - * @Short_description: Struct representing a GInterface - * @Title: GIInterfaceInfo + * @title: GIInterfaceInfo + * @short_description: Struct representing a GInterface * * GIInterfaceInfo represents a #GInterface type. * @@ -297,9 +297,10 @@ g_interface_info_get_signal (GIInterfaceInfo *info, * @info: a #GIInterfaceInfo * @name: Name of signal * + * TODO + * * Returns: (transfer full): Info for the signal with name @name in @info, or * %NULL on failure. - * * Since: 1.34 */ GISignalInfo * diff --git a/girepository/giinterfaceinfo.h b/girepository/giinterfaceinfo.h index ce40cda7..ec33a630 100644 --- a/girepository/giinterfaceinfo.h +++ b/girepository/giinterfaceinfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_INTERFACE_INFO + * @info: an info structure + * + * Checks if @info is a #GIInterfaceInfo. + */ #define GI_IS_INTERFACE_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_INTERFACE) diff --git a/girepository/ginvoke.c b/girepository/ginvoke.c index 5c0ace4c..6eba9fcc 100644 --- a/girepository/ginvoke.c +++ b/girepository/ginvoke.c @@ -28,6 +28,13 @@ #include "girffi.h" #include "config.h" +/** + * value_to_ffi_type: + * @gvalue: TODO + * @value: TODO + * + * TODO + */ static ffi_type * value_to_ffi_type (const GValue *gvalue, gpointer *value) { @@ -89,7 +96,14 @@ value_to_ffi_type (const GValue *gvalue, gpointer *value) return rettype; } -/* See comment aboe set_gargument_from_ffi_return_value() */ +/** + * g_value_to_ffi_return_type: + * @gvalue: TODO + * @ffi_value: TODO + * @value: TODO + * + * TODO + */ static ffi_type * g_value_to_ffi_return_type (const GValue *gvalue, const GIArgument *ffi_value, @@ -153,6 +167,13 @@ g_value_to_ffi_return_type (const GValue *gvalue, return rettype; } +/** + * g_value_from_ffi_value: + * @gvalue: TODO + * @value: TODO + * + * TODO + */ static void g_value_from_ffi_value (GValue *gvalue, const GIArgument *value) @@ -210,6 +231,17 @@ g_value_from_ffi_value (GValue *gvalue, } +/** + * gi_cclosure_marshal_generic: + * @closure: TODO + * @return_gvalue: TODO + * @n_param_values: TODO + * @param_values: TODO + * @invocation_hint: TODO + * @marshal_data: TODO + * + * TODO + */ void gi_cclosure_marshal_generic (GClosure *closure, GValue *return_gvalue, diff --git a/girepository/giobjectinfo.c b/girepository/giobjectinfo.c index 7ba2a93b..b0aff37c 100644 --- a/girepository/giobjectinfo.c +++ b/girepository/giobjectinfo.c @@ -28,8 +28,8 @@ /** * SECTION:giobjectinfo - * @Short_description: Struct representing a GObject - * @Title: GIObjectInfo + * @title: GIObjectInfo + * @short_description: Struct representing a GObject * * GIObjectInfo represents a #GObject. This doesn't represent a specific * instance of a GObject, instead this represent the object type (eg class). @@ -534,6 +534,8 @@ g_object_info_get_signal (GIObjectInfo *info, * @info: a #GIObjectInfo * @name: Name of signal * + * TODO + * * Returns: Info for the signal with name @name in @info, or %NULL on failure. */ GISignalInfo * diff --git a/girepository/giobjectinfo.h b/girepository/giobjectinfo.h index ee4b8a82..06206776 100644 --- a/girepository/giobjectinfo.h +++ b/girepository/giobjectinfo.h @@ -46,7 +46,6 @@ typedef void * (*GIObjectInfoRefFunction) (void *object); * @object: object instance pointer * * Decreases the reference count of an object instance. - * */ typedef void (*GIObjectInfoUnrefFunction) (void *object); @@ -56,7 +55,6 @@ typedef void (*GIObjectInfoUnrefFunction) (void *object); * @object: object instance pointer * * Update @value and attach the object instance pointer @object to it. - * */ typedef void (*GIObjectInfoSetValueFunction) (GValue *value, void *object); @@ -70,6 +68,12 @@ typedef void (*GIObjectInfoSetValueFunction) (GValue *value, void *object); */ typedef void * (*GIObjectInfoGetValueFunction) (const GValue *value); +/** + * GI_IS_OBJECT_INFO + * @info: an info structure + * + * Checks if @info is a #GIObjectInfo. + */ #define GI_IS_OBJECT_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_OBJECT) diff --git a/girepository/gipropertyinfo.c b/girepository/gipropertyinfo.c index 61316cb9..77a11cb8 100644 --- a/girepository/gipropertyinfo.c +++ b/girepository/gipropertyinfo.c @@ -28,8 +28,8 @@ /** * SECTION:gipropertyinfo - * @Short_description: Struct representing a property - * @Title: GIPropertyInfo + * @title: GIPropertyInfo + * @short_description: Struct representing a property * * GIPropertyInfo represents a property. A property belongs to * either a #GIObjectInfo or a #GIInterfaceInfo. @@ -47,7 +47,7 @@ * g_property_info_get_flags: * @info: a #GIPropertyInfo * - * Obtain the flags for this property info. See #GParamFags for + * Obtain the flags for this property info. See #GParamFlags for * more information about possible flag values. * * Returns: the flags diff --git a/girepository/gipropertyinfo.h b/girepository/gipropertyinfo.h index 14b18b41..7644664b 100644 --- a/girepository/gipropertyinfo.h +++ b/girepository/gipropertyinfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_PROPERTY_INFO + * @info: an info structure + * + * Checks if @info is a #GIPropertyInfo. + */ #define GI_IS_PROPERTY_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_PROPERTY) diff --git a/girepository/giregisteredtypeinfo.c b/girepository/giregisteredtypeinfo.c index 6e3d31e2..e45e0603 100644 --- a/girepository/giregisteredtypeinfo.c +++ b/girepository/giregisteredtypeinfo.c @@ -30,8 +30,8 @@ /** * SECTION:giregisteredtypeinfo - * @Short_description: Struct representing a struct with a GType - * @Title: GIRegisteredTypeInfo + * @title: GIRegisteredTypeInfo + * @short_description: Struct representing a struct with a GType * * GIRegisteredTypeInfo represents an entity with a GType associated. Could * be either a #GIEnumInfo, #GIInterfaceInfo, #GIObjectInfo, #GIStructInfo or a diff --git a/girepository/giregisteredtypeinfo.h b/girepository/giregisteredtypeinfo.h index d46d738b..e5db25b4 100644 --- a/girepository/giregisteredtypeinfo.h +++ b/girepository/giregisteredtypeinfo.h @@ -32,6 +32,12 @@ G_BEGIN_DECLS +/** + * GI_IS_REGISTERED_TYPE_INFO + * @info: an info structure + * + * Checks if @info is a #GIRegisteredTypeInfo or derived from it. + */ #define GI_IS_REGISTERED_TYPE_INFO(info) \ ((g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_BOXED) || \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_ENUM) || \ diff --git a/girepository/girepository.c b/girepository/girepository.c index 93c23728..6fc7c77e 100644 --- a/girepository/girepository.c +++ b/girepository/girepository.c @@ -34,6 +34,17 @@ #include "config.h" + +/** + * SECTION:girepository + * @short_description: GObject Introspection repository manager + * @include: girepository.h + * + * #GIRepository is used to manage repositories of namespaces. Namespaces + * are represented on disk by type libraries (.typelib files). + */ + + static GIRepository *default_repository = NULL; static GSList *search_path = NULL; static GSList *override_search_path = NULL; @@ -146,8 +157,9 @@ init_globals (void) char *typelib_dir; const gchar *type_lib_path_env; - /* This variable is intended to take precedence over both the default - * search path, as well as anything written into code with g_irepository_prepend_search_path. + /* This variable is intended to take precedence over both: + * - the default search path; + * - all g_irepository_prepend_search_path() calls. */ type_lib_path_env = g_getenv ("GI_TYPELIB_PATH"); @@ -186,6 +198,14 @@ init_globals (void) g_once_init_leave (&initialized, 1); } +/** + * g_irepository_prepend_search_path: + * @directory: (type filename): directory name to prepend to the typelib + * search path + * + * Prepends @directory to the typelib search path. + * See g_irepository_get_search_path(). + */ void g_irepository_prepend_search_path (const char *directory) { @@ -196,11 +216,11 @@ g_irepository_prepend_search_path (const char *directory) /** * g_irepository_get_search_path: * - * Returns the search path the GIRepository will use when looking for typelibs. - * The string is internal to GIRespository and should not be freed, nor should - * the elements. + * Returns the current search path #GIRepository will use when loading + * typelib files. The list is internal to #GIRespository and should not + * be freed, nor should its string elements. * - * Return value: (element-type filename) (transfer none): list of strings + * Returns: (element-type filename) (transfer none): #GSList of strings */ GSList * g_irepository_get_search_path (void) @@ -412,17 +432,19 @@ register_internal (GIRepository *repository, /** * g_irepository_get_dependencies: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: Namespace of interest * - * Return an array of all (transitive) dependencies for namespace - * @namespace_, including version. The returned strings are of the - * form <code>namespace-version</code>. + * Return an array of all (transitive) versioned dependencies for + * @namespace_. Returned strings are of the form + * <code>namespace-version</code>. * - * Note: The namespace must have already been loaded using a function + * Note: @namespace_ must have already been loaded using a function * such as g_irepository_require() before calling this function. * - * Returns: (transfer full): Zero-terminated string array of versioned dependencies + * Returns: (transfer full): Zero-terminated string array of versioned + * dependencies */ char ** g_irepository_get_dependencies (GIRepository *repository, @@ -440,6 +462,16 @@ g_irepository_get_dependencies (GIRepository *repository, return get_typelib_dependencies (typelib); } +/** + * g_irepository_load_typelib: + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository + * @typelib: TODO + * @flags: TODO + * @error: TODO + * + * TODO + */ const char * g_irepository_load_typelib (GIRepository *repository, GITypelib *typelib, @@ -478,7 +510,8 @@ g_irepository_load_typelib (GIRepository *repository, /** * g_irepository_is_registered: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: Namespace of interest * @version: (allow-none): Required version, may be %NULL for latest * @@ -503,13 +536,13 @@ g_irepository_is_registered (GIRepository *repository, /** * g_irepository_get_default: * - * Returns the singleton process-global default #GIRepository. It is + * Returns the singleton process-global default #GIRepository. It is * not currently supported to have multiple repositories in a * particular process, but this function is provided in the unlikely * eventuality that it would become possible, and as a convenience for * higher level language bindings to conform to the GObject method * call conventions. - + * * All methods on #GIRepository also accept %NULL as an instance * parameter to mean this default repository, which is usually more * convenient for C. @@ -524,7 +557,8 @@ g_irepository_get_default (void) /** * g_irepository_get_n_infos: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: Namespace to inspect * * This function returns the number of metadata entries in @@ -555,7 +589,8 @@ g_irepository_get_n_infos (GIRepository *repository, /** * g_irepository_get_info: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: Namespace to inspect * @index: 0-based offset into namespace metadata for entry * @@ -629,7 +664,8 @@ find_by_gtype (GHashTable *table, FindByGTypeData *data, gboolean check_prefix) /** * g_irepository_find_by_gtype: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @gtype: GType to search for * * Searches all loaded namespaces for a particular #GType. Note that @@ -717,7 +753,8 @@ g_irepository_find_by_gtype (GIRepository *repository, /** * g_irepository_find_by_name: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: Namespace which will be searched * @name: Entry name to find * @@ -776,7 +813,8 @@ find_by_error_domain_foreach (gpointer key, /** * g_irepository_find_by_error_domain: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @domain: a #GError domain * * Searches for the enum type corresponding to the given #GError @@ -786,7 +824,6 @@ find_by_error_domain_foreach (gpointer key, * * Returns: (transfer full): #GIEnumInfo representing metadata about @domain's * enum type, or %NULL - * * Since: 1.29.17 */ GIEnumInfo * @@ -839,7 +876,8 @@ collect_namespaces (gpointer key, /** * g_irepository_get_loaded_namespaces: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * * Return the list of currently loaded namespaces. * @@ -868,7 +906,8 @@ g_irepository_get_loaded_namespaces (GIRepository *repository) /** * g_irepository_get_version: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: Namespace to inspect * * This function returns the loaded version associated with the given @@ -900,7 +939,8 @@ g_irepository_get_version (GIRepository *repository, /** * g_irepository_get_shared_library: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: Namespace to inspect * * This function returns the full path to the shared C library @@ -937,7 +977,8 @@ g_irepository_get_shared_library (GIRepository *repository, /** * g_irepository_get_c_prefix: - * @repository: (allow-none): A #GIRepository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: Namespace to inspect * * This function returns the "C prefix", or the C level namespace @@ -973,13 +1014,14 @@ g_irepository_get_c_prefix (GIRepository *repository, /** * g_irepository_get_typelib_path: - * @repository: (allow-none): Repository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: GI namespace to use, e.g. "Gtk" * * If namespace @namespace_ is loaded, return the full path to the * .typelib file it was loaded from. If the typelib for * namespace @namespace_ was included in a shared library, return - * the special string "$lt;builtin$gt;". + * the special string "<builtin>". * * Returns: Filesystem path (or $lt;builtin$gt;) if successful, %NULL if namespace is not loaded */ @@ -1248,7 +1290,8 @@ find_namespace_latest (const gchar *namespace, /** * g_irepository_enumerate_versions: - * @repository: (allow-none): the repository + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: GI namespace, e.g. "Gtk" * * Obtain an unordered list of versions (either currently loaded or @@ -1408,7 +1451,8 @@ require_internal (GIRepository *repository, /** * g_irepository_require: - * @repository: (allow-none): Repository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @namespace_: GI namespace to use, e.g. "Gtk" * @version: (allow-none): Version of namespace, may be %NULL for latest * @flags: Set of %GIRepositoryLoadFlags, may be 0 @@ -1442,7 +1486,8 @@ g_irepository_require (GIRepository *repository, /** * g_irepository_require_private: - * @repository: (allow-none): Repository, may be %NULL for the default + * @repository: (allow-none): A #GIRepository or %NULL for the singleton + * process-global default #GIRepository * @typelib_dir: Private directory where to find the requested typelib * @namespace_: GI namespace to use, e.g. "Gtk" * @version: (allow-none): Version of namespace, may be %NULL for latest diff --git a/girepository/girepository.h b/girepository/girepository.h index 2b2b1713..dea250df 100644 --- a/girepository/girepository.h +++ b/girepository/girepository.h @@ -56,29 +56,34 @@ G_BEGIN_DECLS #define G_IS_IREPOSITORY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_IREPOSITORY)) #define G_IREPOSITORY_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_IREPOSITORY, GIRepositoryClass)) +/** + * GIRepository: + * + * The GIRepository structure contains private data and should only be + * accessed using the provided API. + */ typedef struct _GIRepository GIRepository; typedef struct _GIRepositoryClass GIRepositoryClass; typedef struct _GIRepositoryPrivate GIRepositoryPrivate; struct _GIRepository { - GObject parent; - /*< private >*/ + GObject parent; GIRepositoryPrivate *priv; }; struct _GIRepositoryClass { + /*< private >*/ GObjectClass parent; }; /** * GIRepositoryLoadFlags: - * @G_IREPOSITORY_LOAD_FLAG_LAZY: Load the types lazily. + * @G_IREPOSITORY_LOAD_FLAG_LAZY: Lazily load the typelib. * - * Flags that controlls how a typelib is loaded by - * GIRepositry, used by g_irepository_load_typelib(). + * Flags that control how a typelib is loaded. */ typedef enum { @@ -144,11 +149,14 @@ gboolean g_irepository_dump (const char *arg, GError **error); * GIRepositoryError: * @G_IREPOSITORY_ERROR_TYPELIB_NOT_FOUND: the typelib could not be found. * @G_IREPOSITORY_ERROR_NAMESPACE_MISMATCH: the namespace does not match the - * requested namespace. + * requested namespace. * @G_IREPOSITORY_ERROR_NAMESPACE_VERSION_CONFLICT: the version of the - * typelib does not match the requested version. + * typelib does not match the requested version. * @G_IREPOSITORY_ERROR_LIBRARY_NOT_FOUND: the library used by the typelib - * could not be found. + * could not be found. + * + * An error code used with #G_IREPOSITORY_ERROR in a #GError returned + * from a #GIRepository routine. */ typedef enum { @@ -158,6 +166,13 @@ typedef enum G_IREPOSITORY_ERROR_LIBRARY_NOT_FOUND } GIRepositoryError; +/** + * G_IREPOSITORY_ERROR: + * + * Error domain for #GIRepository. Errors in this domain will be from the + * #GIRepositoryError enumeration. See #GError for more information on + * error domains. + */ #define G_IREPOSITORY_ERROR (g_irepository_error_quark ()) GQuark g_irepository_error_quark (void); diff --git a/girepository/girffi.c b/girepository/girffi.c index f4c80eaa..30642fe1 100644 --- a/girepository/girffi.c +++ b/girepository/girffi.c @@ -33,6 +33,14 @@ #include "girepository.h" #include "girepository-private.h" +/** + * SECTION:girffi + * @short_description: TODO + * @title: girffi + * + * TODO + */ + static ffi_type * gi_type_tag_get_ffi_type_internal (GITypeTag tag, gboolean is_pointer, @@ -103,22 +111,26 @@ gi_type_tag_get_ffi_type_internal (GITypeTag tag, /** * gi_type_tag_get_ffi_type: - * @tag: A #GITypeTag + * @type_tag: A #GITypeTag * @is_pointer: Whether or not this is a pointer type * + * TODO + * * Returns: A #ffi_type corresponding to the platform default C ABI for @tag and @is_pointer. */ ffi_type * -gi_type_tag_get_ffi_type (GITypeTag tag, +gi_type_tag_get_ffi_type (GITypeTag type_tag, gboolean is_pointer) { - return gi_type_tag_get_ffi_type_internal (tag, is_pointer, FALSE); + return gi_type_tag_get_ffi_type_internal (type_tag, is_pointer, FALSE); } /** * g_type_info_get_ffi_type: * @info: A #GITypeInfo * + * TODO + * * Returns: A #ffi_type corresponding to the platform default C ABI for @info. */ ffi_type * @@ -150,7 +162,9 @@ g_type_info_get_ffi_type (GITypeInfo *info) * @callable_info: a callable info from a typelib * @n_args_p: (out): The number of arguments * - * Return value: an array of ffi_type*. The array itself + * TODO + * + * Returns: an array of ffi_type*. The array itself * should be freed using g_free() after use. */ static ffi_type ** @@ -217,7 +231,8 @@ g_callable_info_get_ffi_arg_types (GICallableInfo *callable_info, * * Fetches the ffi_type for a corresponding return value of * a #GICallableInfo - * Return value: the ffi_type for the return value + * + * Returns: the ffi_type for the return value */ static ffi_type * g_callable_info_get_ffi_return_type (GICallableInfo *callable_info) @@ -316,7 +331,7 @@ g_function_invoker_new_for_address (gpointer addr, } /** - * g_function_info_invoker_destroy: + * g_function_invoker_destroy: * @invoker: A #GIFunctionInvoker * * Release all resources allocated for the internals of @invoker; callers @@ -343,8 +358,8 @@ typedef struct { * * Prepares a callback for ffi invocation. * - * Return value: the ffi_closure or NULL on error. - * The return value should be freed by calling g_callable_info_free_closure(). + * Returns: the ffi_closure or NULL on error. The return value + * should be freed by calling g_callable_info_free_closure(). */ ffi_closure * g_callable_info_prepare_closure (GICallableInfo *callable_info, diff --git a/girepository/girffi.h b/girepository/girffi.h index 56caff73..50cabb17 100644 --- a/girepository/girffi.h +++ b/girepository/girffi.h @@ -27,6 +27,15 @@ G_BEGIN_DECLS +/** + * GIFFIClosureCallback: + * @Param1: TODO + * @Param2: TODO + * @Param3: TODO + * @Param4: TODO + * + * TODO + */ typedef void (*GIFFIClosureCallback) (ffi_cif *, void *, void **, @@ -35,7 +44,9 @@ typedef void (*GIFFIClosureCallback) (ffi_cif *, /** * GIFunctionInvoker: * @cif: the cif - * @native_address: the native adress + * @native_address: the native address + * + * TODO */ typedef struct _GIFunctionInvoker GIFunctionInvoker; @@ -46,6 +57,11 @@ struct _GIFunctionInvoker { gpointer padding[3]; }; +/** + * GIFFIReturnValue: + * + * TODO + */ typedef GIArgument GIFFIReturnValue; ffi_type * gi_type_tag_get_ffi_type (GITypeTag type_tag, gboolean is_pointer); diff --git a/girepository/giroffsets.c b/girepository/giroffsets.c index 368332ea..84278b89 100644 --- a/girepository/giroffsets.c +++ b/girepository/giroffsets.c @@ -497,7 +497,7 @@ check_needs_computation (GIrTypelibBuild *build, return alignment == 0; } -/** +/* * _g_ir_node_compute_offsets: * @build: Current typelib build * @node: a #GIrNode diff --git a/girepository/gisignalinfo.c b/girepository/gisignalinfo.c index f4110c38..be75276e 100644 --- a/girepository/gisignalinfo.c +++ b/girepository/gisignalinfo.c @@ -28,8 +28,8 @@ /** * SECTION:gisignalinfo - * @Short_description: Struct representing a signal - * @Title: GISignalInfo + * @title: GISignalInfo + * @short_description: Struct representing a signal * * GISignalInfo represents a signal. It's a sub-struct of #GICallableInfo * and contains a set of flags and a class closure. diff --git a/girepository/gisignalinfo.h b/girepository/gisignalinfo.h index e3a1e4a4..8502610c 100644 --- a/girepository/gisignalinfo.h +++ b/girepository/gisignalinfo.h @@ -32,6 +32,12 @@ G_BEGIN_DECLS +/** + * GI_IS_SIGNAL_INFO + * @info: an info structure + * + * Checks if @info is a #GISignalInfo. + */ #define GI_IS_SIGNAL_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_SIGNAL) diff --git a/girepository/gistructinfo.c b/girepository/gistructinfo.c index dc17e322..f205e7cf 100644 --- a/girepository/gistructinfo.c +++ b/girepository/gistructinfo.c @@ -28,8 +28,8 @@ /** * SECTION:gistructinfo - * @Short_description: Struct representing a C structure - * @Title: GIStructInfo + * @title: GIStructInfo + * @short_description: Struct representing a C structure * * GIStructInfo represents a generic C structure type. * @@ -212,6 +212,14 @@ g_struct_info_get_alignment (GIStructInfo *info) return blob->alignment; } +/** + * g_struct_info_is_foreign: + * @info: TODO + * + * TODO + * + * Returns: TODO + */ gboolean g_struct_info_is_foreign (GIStructInfo *info) { diff --git a/girepository/gistructinfo.h b/girepository/gistructinfo.h index 1d10708e..4300534d 100644 --- a/girepository/gistructinfo.h +++ b/girepository/gistructinfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_STRUCT_INFO + * @info: an info structure + * + * Checks if @info is a #GIStructInfo. + */ #define GI_IS_STRUCT_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_STRUCT) diff --git a/girepository/gitypeinfo.c b/girepository/gitypeinfo.c index a43fbc1b..3c17f564 100644 --- a/girepository/gitypeinfo.c +++ b/girepository/gitypeinfo.c @@ -28,8 +28,8 @@ /** * SECTION:gitypeinfo - * @Short_description: Struct representing a type - * @Title: GITypeInfo + * @title: GITypeInfo + * @short_description: Struct representing a type * * GITypeInfo represents a type. You can retrieve a type info from * an argument (see #GIArgInfo), a functions return value (see #GIFunctionInfo), @@ -48,7 +48,6 @@ * +----GITypeInfo * </synopsis> * </refsect1> - * */ /** diff --git a/girepository/gitypeinfo.h b/girepository/gitypeinfo.h index ef834b12..7591799a 100644 --- a/girepository/gitypeinfo.h +++ b/girepository/gitypeinfo.h @@ -31,9 +31,21 @@ G_BEGIN_DECLS +/** + * GI_IS_TYPE_INFO + * @info: an info structure + * + * Checks if @info is a #GITypeInfo. + */ #define GI_IS_TYPE_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_TYPE) +/** + * G_TYPE_TAG_IS_BASIC + * @tag: a type tag + * + * Checks if @tag is a basic type. + */ #define G_TYPE_TAG_IS_BASIC(tag) (tag < GI_TYPE_TAG_ARRAY || tag == GI_TYPE_TAG_UNICHAR) const gchar* g_type_tag_to_string (GITypeTag type); diff --git a/girepository/gitypelib-internal.h b/girepository/gitypelib-internal.h index ac71008d..23f4d625 100644 --- a/girepository/gitypelib-internal.h +++ b/girepository/gitypelib-internal.h @@ -30,7 +30,8 @@ G_BEGIN_DECLS /** - * SECTION:gtypelib + * SECTION:gitypelib-internal + * @title: GITypelib * @short_description: Layout and accessors for typelib * @stability: Stable * @@ -42,32 +43,31 @@ G_BEGIN_DECLS * * Some of the differences to XPCOM include: * - Type information is stored not quite as compactly (XPCOM stores it inline - * in function descriptions in variable-sized blobs of 1 to n bytes. We store - * 16 bits of type information for each parameter, which is enough to encode - * simple types inline. Complex (e.g. recursive) types are stored out of line - * in a separate list of types. + * in function descriptions in variable-sized blobs of 1 to n bytes. We store + * 16 bits of type information for each parameter, which is enough to encode + * simple types inline. Complex (e.g. recursive) types are stored out of line + * in a separate list of types. * - String and complex type data is stored outside of typelib entry blobs, - * references are stored as offsets relative to the start of the typelib. - * One possibility is to store the strings and types in a pools at the end - * of the typelib. + * references are stored as offsets relative to the start of the typelib. + * One possibility is to store the strings and types in a pools at the end + * of the typelib. * - * The typelib has the following general format. + * The typelib has the following general format: * - * typelib ::= header, section-index, directory, blobs, attributes, attributedata + * typelib ::= header, section-index, directory, blobs, attributes, attributedata * - * directory ::= list of entries + * directory ::= list of entries * - * entry ::= blob type, name, namespace, offset - * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union - * attributes ::= list of attributes, sorted by offset - * attribute ::= offset, key, value - * attributedata ::= string data for attributes + * entry ::= blob type, name, namespace, offset + * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union + * attribute ::= offset, key, value + * attributedata ::= string data for attributes * * Details * * We describe the fragments that make up the typelib in the form of C structs - * (although some fall short of being valid C structs since they contain multiple - * flexible arrays). + * (although some fall short of being valid C structs since they contain + * multiple flexible arrays). */ /* @@ -157,10 +157,11 @@ Changes since 0.1: * @BLOB_TYPE_OBJECT: An #ObjectBlob * @BLOB_TYPE_INTERFACE: An #InterfaceBlob * @BLOB_TYPE_CONSTANT: A #ConstantBlob + * @BLOB_TYPE_INVALID_0: Deleted, used to be ErrorDomain. * @BLOB_TYPE_UNION: A #UnionBlob * - * The integral value of this enumeration appears in each "Blob" - * component of a typelib to identify its type. + * The integral value of this enumeration appears in each "Blob" component of + * a typelib to identify its type. */ typedef enum { BLOB_TYPE_INVALID, @@ -173,7 +174,7 @@ typedef enum { BLOB_TYPE_OBJECT, BLOB_TYPE_INTERFACE, BLOB_TYPE_CONSTANT, - BLOB_TYPE_INVALID_0, /* DELETED - used to be ErrorDomain */ + BLOB_TYPE_INVALID_0, BLOB_TYPE_UNION } GTypelibBlobType; @@ -188,52 +189,54 @@ typedef enum { /** * Header: * @magic: See #G_IR_MAGIC. - * @major_version: The version of the typelib format. Minor version changes indicate - * compatible changes and should still allow the typelib to be parsed - * by a parser designed for the same major_version. - * @minor_version: See major_version. + * @major_version: The major version number of the typelib format. Major version + * number changes indicate incompatible changes to the tyeplib format. + * @minor_version: The minor version number of the typelib format. Minor version + * number changes indicate compatible changes and should still allow the + * typelib to be parsed by a parser designed for the same @major_version. + * @reserved: Reserved for future use. * @n_entries: The number of entries in the directory. - * @n_local_entries: The number of entries referring to blobs in this typelib. The - * local entries must occur before the unresolved entries. + * @n_local_entries: The number of entries referring to blobs in this typelib. + * The local entries must occur before the unresolved entries. * @directory: Offset of the directory in the typelib. * @n_attributes: Number of attribute blocks * @attributes: Offset of the list of attributes in the typelib. - * @dependencies: Offset of a single string, which is the list of - * dependencies, separated by the '|' character. The - * dependencies are required in order to avoid having programs - * consuming a typelib check for an "Unresolved" type return - * from every API call. + * @dependencies: Offset of a single string, which is the list of dependencies, + * separated by the '|' character. The dependencies are required in order + * to avoid having programs consuming a typelib check for an "Unresolved" + * type return from every API call. * @size: The size in bytes of the typelib. * @namespace: Offset of the namespace string in the typelib. * @nsversion: Offset of the namespace version string in the typelib. - * @shared_library: This field is the set of shared libraries associated - * with the typelib. The entries are separated by the '|' (pipe) character. + * @shared_library: This field is the set of shared libraries associated with + * the typelib. The entries are separated by the '|' (pipe) character. * @c_prefix: The prefix for the function names of the library - * @entry_blob_size: The sizes of fixed-size blobs. Recording this information here - * allows to write parser which continue to work if the format is - * extended by adding new fields to the end of the fixed-size blobs. - * @function_blob_size: See above. - * @callback_blob_size: See above. - * @signal_blob_size: See above. - * @vfunc_blob_size: See above. - * @arg_blob_size: See above. - * @property_blob_size: See above. - * @field_blob_size: See above. - * @value_blob_size: See above. - * @attribute_blob_size: See above. - * @constant_blob_size: See above. - * @object_blob_size: See above. - * @union_blob_size: See above. - * @signature_blob_size: See above. - * @enum_blob_size: See above. - * @struct_blob_size: See above. - * @error_domain_blob_size: See above. - * @interface_blob_size: For variable-size blobs, the size of the struct up to the first - * flexible array member. Recording this information here allows to - * write parser which continue to work if the format is extended by - * adding new fields before the first flexible array member in - * variable-size blobs. + * @entry_blob_size: The sizes of fixed-size blobs. Recording this information + * here allows to write parser which continue to work if the format is + * extended by adding new fields to the end of the fixed-size blobs. + * @function_blob_size: See @entry_blob_size. + * @callback_blob_size: See @entry_blob_size. + * @signal_blob_size: See @entry_blob_size. + * @vfunc_blob_size: See @entry_blob_size. + * @arg_blob_size: See @entry_blob_size. + * @property_blob_size: See @entry_blob_size. + * @field_blob_size: See @entry_blob_size. + * @value_blob_size: See @entry_blob_size. + * @attribute_blob_size: See @entry_blob_size. + * @constant_blob_size: See @entry_blob_size. + * @error_domain_blob_size: See @entry_blob_size. + * @signature_blob_size: See @entry_blob_size. + * @enum_blob_size: See @entry_blob_size. + * @struct_blob_size: See @entry_blob_size. + * @object_blob_size: See @entry_blob_size. + * @interface_blob_size: For variable-size blobs, the size of the struct up to + * the first flexible array member. Recording this information here allows + * to write parser which continue to work if the format is extended by + * adding new fields before the first flexible array member in + * variable-size blobs. + * @union_blob_size: See @entry_blob_size. * @sections: Offset of section blob array + * @padding: TODO * * The header structure appears exactly once at the beginning of a typelib. It is a * collection of meta-information, such as the number of entries and dependencies. @@ -242,9 +245,7 @@ typedef struct { gchar magic[16]; guint8 major_version; guint8 minor_version; - /* <private> */ guint16 reserved; - /* <public> */ guint16 n_entries; guint16 n_local_entries; guint32 directory; @@ -281,10 +282,16 @@ typedef struct { guint32 sections; - /* <private> */ guint16 padding[6]; } Header; +/** + * SectionType: + * @GI_SECTION_END: TODO + * @GI_SECTION_DIRECTORY_INDEX: TODO + * + * TODO + */ typedef enum { GI_SECTION_END = 0, GI_SECTION_DIRECTORY_INDEX = 1 @@ -299,7 +306,6 @@ typedef enum { * and may or may not be present in the typelib. Presently, just used * for the directory index. This allows a form of dynamic extensibility * with different tradeoffs from the format minor version. - * */ typedef struct { guint32 id; @@ -311,10 +317,11 @@ typedef struct { * DirEntry: * @blob_type: A #GTypelibBlobType * @local: Whether this entry refers to a blob in this typelib. + * @reserved: Reserved for future use. * @name: The name of the entry. - * @offset: If is_local is set, this is the offset of the blob in the typelib. - * Otherwise, it is the offset of the namespace in which the blob has - * to be looked up by name. + * @offset: If is_local is set, this is the offset of the blob in the typelib. + * Otherwise, it is the offset of the namespace in which the blob has to be + * looked up by name. * * References to directory entries are stored as 1-based 16-bit indexes. * @@ -325,91 +332,100 @@ typedef struct { guint16 blob_type; guint16 local : 1; - /* <private> */ guint16 reserved :15; - /* <public> */ guint32 name; guint32 offset; } DirEntry; /** - * SimpleTypeBlob: - * @is_pointer: Indicates whether the type is passed by reference. + * SimpleTypeBlobFlags: + * @reserved: Reserved for future use. + * @reserved2: Reserved for future use. + * @pointer: TODO + * @reserved3: Reserved for future use. * @tag: A #GITypeTag - * @offset: Offset relative to header->types that points to a TypeBlob. - * Unlike other offsets, this is in words (ie 32bit units) rather - * than bytes. - * - * The SimpleTypeBlob is the general purpose "reference to a type" construct, used - * in method parameters, returns, callback definitions, fields, constants, etc. - * It's actually just a 32 bit integer which you can see from the union definition. - * This is for efficiency reasons, since there are so many references to types. - * - * SimpleTypeBlob is divided into two cases; first, if "reserved" and "reserved2", the - * type tag for a basic type is embedded in the "tag" bits. This allows e.g. - * GI_TYPE_TAG_UTF8, GI_TYPE_TAG_INT and the like to be embedded directly without - * taking up extra space. * - * References to "interfaces" (objects, interfaces) are more complicated; In this case, - * the integer is actually an offset into the directory (see above). Because the header - * is larger than 2^8=256 bits, all offsets will have one of the upper 24 bits set. + * TODO */ -typedef union +typedef struct { + guint reserved : 8; + guint reserved2 :16; + guint pointer : 1; + guint reserved3 : 2; + guint tag : 5; +} SimpleTypeBlobFlags; + +union _SimpleTypeBlob { - struct - { - /* <private> */ - guint reserved : 8; - guint reserved2 :16; - /* <public> */ - guint pointer : 1; - /* <private> */ - guint reserved3 : 2; - /* <public> */ - guint tag : 5; - } flags; + SimpleTypeBlobFlags flags; guint32 offset; -} SimpleTypeBlob; +}; + +/** + * SimpleTypeBlob: + * @flags: TODO + * @offset: Offset relative to header->types that points to a TypeBlob. + * Unlike other offsets, this is in words (ie 32bit units) rather + * than bytes. + * + * The SimpleTypeBlob is the general purpose "reference to a type" construct, + * used in method parameters, returns, callback definitions, fields, constants, + * etc. It's actually just a 32 bit integer which you can see from the union + * definition. This is for efficiency reasons, since there are so many + * references to types. + * + * SimpleTypeBlob is divided into two cases; first, if "reserved" and + * "reserved2", the type tag for a basic type is embedded in the "tag" bits. + * This allows e.g. GI_TYPE_TAG_UTF8, GI_TYPE_TAG_INT and the like to be + * embedded directly without taking up extra space. + * + * References to "interfaces" (objects, interfaces) are more complicated; + * In this case, the integer is actually an offset into the directory (see + * above). Because the header is larger than 2^8=256 bits, all offsets will + * have one of the upper 24 bits set. + */ +typedef union _SimpleTypeBlob SimpleTypeBlob; /** * ArgBlob: * @name: A suggested name for the parameter. * @in: The parameter is an input to the function - * @out: The parameter is used to return an output of the function. - * Parameters can be both in and out. Out parameters implicitly - * add another level of indirection to the parameter type. Ie if - * the type is uint32 in an out parameter, the function actually - * takes an uint32*. - * @caller_allocates: The parameter is a pointer to a struct or object that will - * receive an output of the function. - * @allow_none: Only meaningful for types which are passed as pointers. - * For an in parameter, indicates if it is ok to pass NULL in, for - * an out parameter, whether it may return NULL. Note that NULL is a - * valid GList and GSList value, thus allow_none will normally be set - * for parameters of these types. + * @out: The parameter is used to return an output of the function. Parameters + * can be both in and out. Out parameters implicitly add another level of + * indirection to the parameter type. Ie if the type is uint32 in an out + * parameter, the function actually takes an uint32*. + * @caller_allocates: The parameter is a pointer to a struct or object that + * will receive an output of the function. + * @allow_none: Only meaningful for types which are passed as pointers. For an + * in parameter, indicates if it is ok to pass NULL in. Gor an out + * parameter, indicates whether it may return NULL. Note that NULL is a + * valid GList and GSList value, thus allow_none will normally be set + * for parameters of these types. * @optional: For an out parameter, indicates that NULL may be passed in - * if the value is not needed. - * @transfer_ownership: For an in parameter, indicates that the function takes over - * ownership of the parameter value. For an out parameter, it - * indicates that the caller is responsible for freeing the return - * value. + * if the value is not needed. + * @transfer_ownership: For an in parameter, indicates that the function takes + * over ownership of the parameter value. For an out parameter, it indicates + * that the caller is responsible for freeing the return value. * @transfer_container_ownership: For container types, indicates that the - * ownership of the container, but not of its contents is transferred. This is typically the case - * for out parameters returning lists of statically allocated things. - * @return_value: The parameter should be considered the return value of the function. - * Only out parameters can be marked as return value, and there can be - * at most one per function call. If an out parameter is marked as - * return value, the actual return value of the function should be - * either void or a boolean indicating the success of the call. - * @scope: A #GIScopeType. If the parameter is of a callback type, this denotes the scope - * of the user_data and the callback function pointer itself - * (for languages that emit code at run-time). - * @closure: Index of the closure (user_data) parameter associated with the callback, - * or -1. - * @destroy: Index of the destroy notfication callback parameter associated with - * the callback, or -1. - * @arg_type: Describes the type of the parameter. See details below. + * ownership of the container, but not of its contents is transferred. + * This is typically the case for out parameters returning lists of + * statically allocated things. + * @return_value: The parameter should be considered the return value of the + * function. Only out parameters can be marked as return value, and there + * can be at most one per function call. If an out parameter is marked as + * return value, the actual return value of the function should be either + * void or a boolean indicating the success of the call. + * @scope: A #GIScopeType. If the parameter is of a callback type, this denotes + * the scope of the user_data and the callback function pointer itself + * (for languages that emit code at run-time). * @skip: Indicates that the parameter is only useful in C and should be skipped. + * @reserved: Reserved for future use. + * @closure: Index of the closure (user_data) parameter associated with the + * callback, or -1. + * @destroy: Index of the destroy notfication callback parameter associated + * with the callback, or -1. + * @padding: TODO + * @arg_type: Describes the type of the parameter. See details below. * * Types are specified by four bytes. If the three high bytes are zero, * the low byte describes a basic type, otherwise the 32bit number is an @@ -428,15 +444,11 @@ typedef struct { guint return_value : 1; guint scope : 3; guint skip : 1; - /* <private> */ guint reserved :20; - /* <public> */ - gint8 closure; - gint8 destroy; + gint8 closure; + gint8 destroy; - /* <private> */ - guint16 padding; - /* <public> */ + guint16 padding; SimpleTypeBlob arg_type; } ArgBlob; @@ -444,17 +456,21 @@ typedef struct { /** * SignatureBlob: * @return_type: Describes the type of the return value. See details below. - * @may_return_null: Only relevant for pointer types. Indicates whether the caller - * must expect NULL as a return value. - * @caller_owns_return_value: If set, the caller is responsible for freeing the return value - * if it is no longer needed. - * @caller_owns_return_container: This flag is only relevant if the return type is a container type. - * If the flag is set, the caller is resonsible for freeing the - * container, but not its contents. - * @skip_return: Indicates that the return value is only useful in C and should be skipped. - * @n_arguments: The number of arguments that this function expects, also the length - * of the array of ArgBlobs. + * @may_return_null: Only relevant for pointer types. Indicates whether the + * caller must expect NULL as a return value. + * @caller_owns_return_value: If set, the caller is responsible for freeing + * the return value if it is no longer needed. + * @caller_owns_return_container: This flag is only relevant if the return type + * is a container type. If the flag is set, the caller is resonsible for + * freeing the container, but not its contents. + * @skip_return: Indicates that the return value is only useful in C and should + * be skipped. + * @reserved: Reserved for future use. + * @n_arguments: The number of arguments that this function expects, also the + * length of the array of ArgBlobs. * @arguments: An array of ArgBlob for the arguments of the function. + * + * TODO */ typedef struct { SimpleTypeBlob return_type; @@ -474,43 +490,50 @@ typedef struct { * CommonBlob: * @blob_type: A #GTypelibBlobType * @deprecated: Whether the blob is deprecated. + * @reserved: Reserved for future use. * @name: The name of the blob. * * The #CommonBlob is shared between #FunctionBlob, * #CallbackBlob, #SignalBlob. + * + * TODO */ typedef struct { guint16 blob_type; /* 1 */ guint16 deprecated : 1; - /* <private> */ guint16 reserved :15; - /* <public> */ guint32 name; } CommonBlob; /** * FunctionBlob: - * @blob_Type: #BLOB_TYPE_FUNCTION - * @symbol: The symbol which can be used to obtain the function pointer with - * dlsym(). + * @blob_type: #BLOB_TYPE_FUNCTION * @deprecated: The function is deprecated. * @setter: The function is a setter for a property. Language bindings may - * prefer to not bind individual setters and rely on the generic - * g_object_set(). + * prefer to not bind individual setters and rely on the generic + * g_object_set(). * @getter: The function is a getter for a property. Language bindings may - * prefer to not bind individual getters and rely on the generic - * g_object_get(). - * @constructor:The function acts as a constructor for the object it is contained - * in. + * prefer to not bind individual getters and rely on the generic + * g_object_get(). + * @constructor: The function acts as a constructor for the object it is + * contained in. * @wraps_vfunc: The function is a simple wrapper for a virtual function. + * @throws: TODO * @index: Index of the property that this function is a setter or getter of - * in the array of properties of the containing interface, or index - * of the virtual function that this function wraps. + * in the array of properties of the containing interface, or index + * of the virtual function that this function wraps. + * @name: TODO + * @symbol: The symbol which can be used to obtain the function pointer with + * dlsym(). * @signature: Offset of the SignatureBlob describing the parameter types and the - * return value type. + * return value type. * @is_static: The function is a "static method"; in other words it's a pure - * function whose name is conceptually scoped to the object. + * function whose name is conceptually scoped to the object. + * @reserved: Reserved for future use. + * @reserved2: Reserved for future use. + * + * TODO */ typedef struct { guint16 blob_type; /* 1 */ @@ -537,16 +560,20 @@ typedef struct { /** * CallbackBlob: - * @signature: Offset of the #SignatureBlob describing the parameter types and the - * return value type. + * @blob_type: TODO + * @deprecated: TODO + * @reserved: Reserved for future use. + * @name: TODO + * @signature: Offset of the #SignatureBlob describing the parameter types and + * the return value type. + * + * TODO */ typedef struct { guint16 blob_type; /* 2 */ guint16 deprecated : 1; - /* <private> */ guint16 reserved :15; - /* <public> */ guint32 name; guint32 signature; } CallbackBlob; @@ -554,41 +581,52 @@ typedef struct { /** * InterfaceTypeBlob: * @pointer: Whether this type represents an indirection + * @reserved: Reserved for future use. * @tag: A #GITypeTag + * @reserved2: Reserved for future use. * @interface: Index of the directory entry for the interface. * * If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1. */ typedef struct { guint8 pointer :1; - /* <private> */ guint8 reserved :2; - /* <public> */ guint8 tag :5; - /* <private> */ guint8 reserved2; - /* <public> */ guint16 interface; } InterfaceTypeBlob; /** + * ArrayTypeDimension: + * @length: TODO + * @size: TODO + * + * TODO + */ +typedef union { + guint16 length; + guint16 size; +} ArrayTypeDimension; + +/** * ArrayTypeBlob: - * @zero_terminated: Indicates that the array must be terminated by a suitable #NULL - * value. - * @has_length: Indicates that length points to a parameter specifying the length - * of the array. If both has_length and zero_terminated are set, the - * convention is to pass -1 for the length if the array is - * zero-terminated. + * @pointer: TODO + * @reserved: Reserved for future use. + * @tag: TODO + * @zero_terminated: Indicates that the array must be terminated by a suitable + * #NULL value. + * @has_length: Indicates that length points to a parameter specifying the + * length of the array. If both has_length and zero_terminated are set, the + * convention is to pass -1 for the length if the array is zero-terminated. * @has_size: Indicates that size is the fixed size of the array. * @array_type: Indicates whether this is a C array, GArray, GPtrArray, or - * GByteArray. If something other than a C array, the length and element size - * are implicit in the structure. - * @length: The index of the parameter which is used to pass the length of the - * array. The parameter must be an integer type and have the same - * direction as this one. - * @size: The fixed size of the array. - * @type: The type of the array elements. - * Arrays are passed by reference, thus is_pointer is always 1. + * GByteArray. If something other than a C array, the length and element + * size are implicit in the structure. + * @reserved2: Reserved for future use. + * @dimensions: TODO + * @type: TODO + * + * TODO */ typedef struct { guint16 pointer :1; @@ -601,19 +639,21 @@ typedef struct { guint16 array_type :2; guint16 reserved2 :3; - union { - guint16 length; - guint16 size; - } dimensions; + ArrayTypeDimension dimensions; SimpleTypeBlob type; } ArrayTypeBlob; /** * ParamTypeBlob: + * @pointer: TODO + * @reserved: Reserved for future use. + * @tag: TODO + * @reserved2: Reserved for future use. * @n_types: The number of parameter types to follow. * @type: Describes the type of the list elements. * + * TODO */ typedef struct { guint8 pointer :1; @@ -628,6 +668,14 @@ typedef struct { /** * ErrorTypeBlob: + * @pointer: TODO + * @reserved: TODO + * @tag: TODO + * @reserved2: TODO + * @n_domains: TODO: must be 0 + * @domains: TODO + * + * TODO */ typedef struct { guint8 pointer :1; @@ -644,17 +692,16 @@ typedef struct { * ValueBlob: * @deprecated: Whether this value is deprecated * @unsigned_value: if set, value is a 32-bit unsigned integer cast to gint32 - * @value: The numerical value + * @reserved: Reserved for future use. * @name: Name of blob + * @value: The numerical value * * Values commonly occur in enums and flags. */ typedef struct { guint32 deprecated : 1; guint32 unsigned_value : 1; - /* <private> */ guint32 reserved :30; - /* <public> */ guint32 name; gint32 value; } ValueBlob; @@ -662,15 +709,18 @@ typedef struct { /** * FieldBlob: * @name: The name of the field. - * @readable: + * @readable: TODO * @writable: How the field may be accessed. * @has_embedded_type: An anonymous type follows the FieldBlob. + * @reserved: Reserved for future use. * @bits: If this field is part of a bitfield, the number of bits which it - * uses, otherwise 0. - * @struct_offset: - * The offset of the field in the struct. The value 0xFFFF indicates - * that the struct offset is unknown. + * uses, otherwise 0. + * @struct_offset: The offset of the field in the struct. The value 0xFFFF + * indicates that the struct offset is unknown. + * @reserved2: Reserved for future use. * @type: The type of the field. + * + * TODO */ typedef struct { guint32 name; @@ -690,8 +740,16 @@ typedef struct { /** * RegisteredTypeBlob: + * @blob_type: TODO + * @deprecated: TODO + * @unregistered: TODO + * @reserved: Reserved for future use. + * @name: TODO * @gtype_name: The name under which the type is registered with GType. - * @gtype_init: The symbol name of the get_type() function which registers the type. + * @gtype_init: The symbol name of the get_type<!-- -->() function which registers the + * type. + * + * TODO */ typedef struct { guint16 blob_type; @@ -709,16 +767,22 @@ typedef struct { * @blob_type: #BLOB_TYPE_STRUCT * @deprecated: Whether this structure is deprecated * @unregistered: If this is set, the type is not registered with GType. + * @is_gtype_struct: Whether this structure is the class or interface layout + * for a GObject * @alignment: The byte boundary that the struct is aligned to in memory - * @is_gtype_struct: Whether this structure is the class or interface layout for a GObject * @foreign: If the type is foreign, eg if it's expected to be overridden by - * a native language binding instead of relying of introspected bindings. - * @size: The size of the struct in bytes. + * a native language binding instead of relying of introspected bindings. + * @reserved: Reserved for future use. + * @name: TODO * @gtype_name: String name of the associated #GType * @gtype_init: String naming the symbol which gets the runtime #GType - * @n_fields: - * @fields: An array of n_fields FieldBlobs. - * should be considered as methods of the struct. + * @size: The size of the struct in bytes. + * @n_fields: TODO + * @n_methods: TODO + * @reserved2: Reserved for future use. + * @reserved3: Reserved for future use. + * + * TODO */ typedef struct { guint16 blob_type; @@ -742,29 +806,30 @@ typedef struct { guint32 reserved2; guint32 reserved3; - -#if 0 - /* variable-length parts of the blob */ - FieldBlob fields[]; - FunctionBlob methods[]; -#endif } StructBlob; /** * UnionBlob: + * @blob_type: TODO + * @deprecated: TODO * @unregistered: If this is set, the type is not registered with GType. * @discriminated: Is set if the union is discriminated * @alignment: The byte boundary that the union is aligned to in memory - * @size: The size of the union in bytes. + * @reserved: Reserved for future use. + * @name: TODO * @gtype_name: String name of the associated #GType * @gtype_init: String naming the symbol which gets the runtime #GType + * @size: TODO * @n_fields: Length of the arrays + * @n_functions: TODO + * @reserved2: Reserved for future use. + * @reserved3: Reserved for future use. * @discriminator_offset: Offset from the beginning of the union where the - * discriminator of a discriminated union is located. - * The value 0xFFFF indicates that the discriminator offset - * is unknown. + * discriminator of a discriminated union is located. The value 0xFFFF + * indicates that the discriminator offset is unknown. * @discriminator_type: Type of the discriminator - * @fields: Array of FieldBlobs describing the alternative branches of the union + * + * TODO */ typedef struct { guint16 blob_type; @@ -788,27 +853,25 @@ typedef struct { gint32 discriminator_offset; SimpleTypeBlob discriminator_type; - -#if 0 - FieldBlob fields[]; - FunctionBlob functions[]; - ConstantBlob discriminator_values[] -#endif } UnionBlob; /** * EnumBlob: + * @blob_type: TODO + * @deprecated: TODO * @unregistered: If this is set, the type is not registered with GType. * @storage_type: The tag of the type used for the enum in the C ABI - * (will be a signed or unsigned integral type) + * (will be a signed or unsigned integral type) + * @reserved: Reserved for future use. + * @name: TODO * @gtype_name: String name of the associated #GType * @gtype_init: String naming the symbol which gets the runtime #GType - * @error_domain: String naming the #GError domain this enum is - * associated with * @n_values: The length of the values array. * @n_methods: The length of the methods array. - * @values: Describes the enum values. - * @methods: Describes the enum methods. + * @error_domain: String naming the #GError domain this enum is associated with + * @values: TODO + * + * TODO */ typedef struct { guint16 blob_type; @@ -829,25 +892,28 @@ typedef struct { guint32 error_domain; ValueBlob values[]; -#if 0 - FunctionBlob methods[]; -#endif } EnumBlob; /** * PropertyBlob: - * @name: The name of the property. - * @readable: - * @writable: - * @construct: + * @name: The name of the property. + * @deprecated: TODO + * @readable: TODO + * @writable: TODO + * @construct: TODO * @construct_only: The ParamFlags used when registering the property. * @transfer_ownership: When writing, the type containing the property takes - * ownership of the value. When reading, the returned value needs to be released - * by the caller. + * ownership of the value. When reading, the returned value needs to be + * released by the caller. * @transfer_container_ownership: For container types indicates that the - * ownership of the container, but not of its contents, is transferred. This is - * typically the case when reading lists of statically allocated things. + * ownership of the container, but not of its contents, is transferred. + * This is typically the case when reading lists of statically allocated + * things. + * @reserved: Reserved for future use. + * @reserved2: Reserved for future use. * @type: Describes the type of the property. + * + * TODO */ typedef struct { guint32 name; @@ -868,20 +934,25 @@ typedef struct { /** * SignalBlob: - * @name: The name of the signal. - * @run_first: - * @run_last: - * @run_cleanup: - * @no_recurse: - * @detailed: - * @action: + * @deprecated: TODO + * @run_first: TODO + * @run_last: TODO + * @run_cleanup: TODO + * @no_recurse: TODO + * @detailed: TODO + * @action: TODO * @no_hooks: The flags used when registering the signal. * @has_class_closure: Set if the signal has a class closure. * @true_stops_emit: Whether the signal has true-stops-emit semantics - * @class_closure: The index of the class closure in the list of virtual functions - * of the object or interface on which the signal is defined. - * @signature: Offset of the SignatureBlob describing the parameter types and the - * return value type. + * @reserved: Reserved for future use. + * @class_closure: The index of the class closure in the list of virtual + * functions of the object or interface on which the signal is defined. + * @name: The name of the signal. + * @reserved2: Reserved for future use. + * @signature: Offset of the SignatureBlob describing the parameter types + * and the return value type. + * + * TODO */ typedef struct { guint16 deprecated : 1; @@ -909,19 +980,28 @@ typedef struct { * VFuncBlob: * @name: The name of the virtual function. * @must_chain_up: If set, every implementation of this virtual function must - * chain up to the implementation of the parent class. - * @must_be_implemented: If set, every derived class must override this virtual function. - * @must_not_be_implemented: If set, derived class must not override this virtual function. - * @class_closure: Set if this virtual function is the class closure of a signal. + * chain up to the implementation of the parent class. + * @must_be_implemented: If set, every derived class must override this virtual + * function. + * @must_not_be_implemented: If set, derived class must not override this + * virtual function. + * @class_closure: Set if this virtual function is the class closure of a + * signal. + * @throws: TODO + * @reserved: Reserved for future use. * @signal: The index of the signal in the list of signals of the object or - * interface to which this virtual function belongs. - * @struct_offset: The offset of the function pointer in the class struct. The value - * 0xFFFF indicates that the struct offset is unknown. - * @invoker: If a method invoker for this virtual exists, this is the offset in the - * class structure of the method. If no method is known, this value will be 0x3ff. - * @signature: - * Offset of the SignatureBlob describing the parameter types and the - * return value type. + * interface to which this virtual function belongs. + * @struct_offset: The offset of the function pointer in the class struct. + * The value 0xFFFF indicates that the struct offset is unknown. + * @invoker: If a method invoker for this virtual exists, this is the offset + * in the class structure of the method. If no method is known, this value + * will be 0x3ff. + * @reserved2: Reserved for future use. + * @reserved3: Reserved for future use. + * @signature: Offset of the SignatureBlob describing the parameter types and + * the return value type. + * + * TODO */ typedef struct { guint32 name; @@ -945,36 +1025,41 @@ typedef struct { /** * ObjectBlob: * @blob_type: #BLOB_TYPE_OBJECT + * @deprecated: TODO + * @abstract: TODO * @fundamental: this object is not a GObject derived type, instead it's - * an additional fundamental type. + * an additional fundamental type. + * @reserved: Reserved for future use. + * @name: TODO * @gtype_name: String name of the associated #GType * @gtype_init: String naming the symbol which gets the runtime #GType * @parent: The directory index of the parent type. This is only set for - * objects. If an object does not have a parent, it is zero. - * @n_interfaces: - * @n_fields: - * @n_properties: - * @n_methods: - * @n_signals: - * @n_vfuncs: - * @n_constants: The lengths of the arrays.Up to 16bits of padding may be inserted - * between the arrays to ensure that they start on a 32bit boundary. - * @interfaces: An array of indices of directory entries for the implemented - * interfaces. - * @fields: Describes the fields. - * @methods: Describes the methods, constructors, setters and getters. - * @properties: Describes the properties. - * @signals: Describes the signals. - * @vfuncs: Describes the virtual functions. - * @constants: Describes the constants. + * objects. If an object does not have a parent, it is zero. + * @gtype_struct: TODO + * @n_interfaces: TODO + * @n_fields: TODO + * @n_properties: TODO + * @n_methods: TODO + * @n_signals: TODO + * @n_vfuncs: TODO + * @n_constants: The lengths of the arrays.Up to 16bits of padding may be + * inserted between the arrays to ensure that they start on a 32bit + * boundary. + * @reserved2: Reserved for future use. * @ref_func: String pointing to a function which can be called to increase - * the reference count for an instance of this object type. + * the reference count for an instance of this object type. * @unref_func: String pointing to a function which can be called to decrease - * the reference count for an instance of this object type. + * the reference count for an instance of this object type. * @set_value_func: String pointing to a function which can be called to - * convert a pointer of this object to a GValue + * convert a pointer of this object to a GValue * @get_value_func: String pointing to a function which can be called to - * convert extract a pointer to this object from a GValue + * convert extract a pointer to this object from a GValue + * @reserved3: Reserved for future use. + * @reserved4: Reserved for future use. + * @interfaces: An array of indices of directory entries for the implemented + * interfaces. + * + * TODO */ typedef struct { guint16 blob_type; /* 7 */ @@ -1008,35 +1093,32 @@ typedef struct { guint32 reserved4; guint16 interfaces[]; - -#if 0 - /* variable-length parts of the blob */ - FieldBlob fields[]; - PropertyBlob properties[]; - FunctionBlob methods[]; - SignalBlob signals[]; - VFuncBlob vfuncs[]; - ConstantBlob constants[]; -#endif } ObjectBlob; /** * InterfaceBlob: + * @blob_type: TODO + * @deprecated: TODO + * @reserved: Reserved for future use. + * @name: TODO + * @gtype_name: TODO + * @gtype_init: TODO * @gtype_struct: Name of the interface "class" C structure * @n_prerequisites: Number of prerequisites * @n_properties: Number of properties * @n_methods: Number of methods * @n_signals: Number of signals * @n_vfuncs: Number of virtual functions - * @n_constants: The lengths of the arrays. - * Up to 16bits of padding may be inserted between the arrays to ensure that they - * start on a 32bit boundary. - * @prerequisites: An array of indices of directory entries for required interfaces. - * @methods: Describes the methods, constructors, setters and getters. - * @properties: Describes the properties. - * @signals: Describes the signals. - * @vfuncs: Describes the virtual functions. - * @constants: Describes the constants. + * @n_constants: The lengths of the arrays. Up to 16bits of padding may be + * inserted between the arrays to ensure that they start on a 32bit + * boundary. + * @padding: TODO + * @reserved2: Reserved for future use. + * @reserved3: Reserved for future use. + * @prerequisites: An array of indices of directory entries for required + * interfaces. + * + * TODO */ typedef struct { guint16 blob_type; @@ -1061,23 +1143,21 @@ typedef struct { guint32 reserved3; guint16 prerequisites[]; - -#if 0 - /* variable-length parts of the blob */ - PropertyBlob properties[]; - FunctionBlob methods[]; - SignalBlob signals[]; - VFuncBlob vfuncs[]; - ConstantBlob constants[]; -#endif } InterfaceBlob; /** * ConstantBlob: - * @type: The type of the value. In most cases this should be a numeric - * type or string. + * @blob_type: TODO + * @deprecated: TODO + * @reserved: Reserved for future use. + * @name: TODO + * @type: The type of the value. In most cases this should be a numeric type + * or string. * @size: The size of the value in bytes. * @offset: The offset of the value in the typelib. + * @reserved2: Reserved for future use. + * + * TODO */ typedef struct { guint16 blob_type; @@ -1096,10 +1176,12 @@ typedef struct { /** * AttributeBlob: * @offset: The offset of the typelib entry to which this attribute refers. - * Attributes are kept sorted by offset, so that the attributes - * of an entry can be found by a binary search. + * Attributes are kept sorted by offset, so that the attributes of an + * entry can be found by a binary search. * @name: The name of the attribute, a string. * @value: The value of the attribute (also a string) + * + * TODO */ typedef struct { guint32 offset; @@ -1107,9 +1189,6 @@ typedef struct { guint32 value; } AttributeBlob; -/** - * GITypelib: - */ struct _GITypelib { /* <private> */ guchar *data; @@ -1137,6 +1216,15 @@ gboolean g_typelib_matches_gtype_name_prefix (GITypelib *typelib, void g_typelib_check_sanity (void); +/** + * g_typelib_get_string: + * @typelib: TODO + * @offset: TODO + * + * TODO + * + * Returns: TODO + */ #define g_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)]) @@ -1159,6 +1247,11 @@ typedef enum G_TYPELIB_ERROR_INVALID_BLOB } GITypelibError; +/** + * G_TYPELIB_ERROR: + * + * TODO + */ #define G_TYPELIB_ERROR (g_typelib_error_quark ()) GQuark g_typelib_error_quark (void); @@ -1171,6 +1264,11 @@ gboolean g_typelib_validate (GITypelib *typelib, AttributeBlob *_attribute_blob_find_first (GIBaseInfo *info, guint32 blob_offset); +/** + * GITypelibHashBuilder: + * + * TODO + */ typedef struct _GITypelibHashBuilder GITypelibHashBuilder; GITypelibHashBuilder * _gi_typelib_hash_builder_new (void); diff --git a/girepository/gitypelib.c b/girepository/gitypelib.c index 1436caf1..8883496e 100644 --- a/girepository/gitypelib.c +++ b/girepository/gitypelib.c @@ -130,6 +130,15 @@ get_type_blob (GITypelib *typelib, return (InterfaceTypeBlob*) get_blob (typelib, simple->offset, error); } +/** + * g_typelib_get_dir_entry: + * @typelib: TODO + * @index: TODO + * + * TODO + * + * Returns: TODO + */ DirEntry * g_typelib_get_dir_entry (GITypelib *typelib, guint16 index) @@ -159,6 +168,15 @@ get_section_by_id (GITypelib *typelib, return NULL; } +/** + * g_typelib_get_dir_entry_by_name: + * @typelib: TODO + * @name: TODO + * + * TODO + * + * Returns: TODO + */ DirEntry * g_typelib_get_dir_entry_by_name (GITypelib *typelib, const char *name) @@ -196,6 +214,15 @@ g_typelib_get_dir_entry_by_name (GITypelib *typelib, } } +/** + * g_typelib_get_dir_entry_by_gtype_name: + * @typelib: TODO + * @gtype_name: TODO + * + * TODO + * + * Returns: TODO + */ DirEntry * g_typelib_get_dir_entry_by_gtype_name (GITypelib *typelib, const gchar *gtype_name) @@ -281,6 +308,15 @@ strsplit_iter_clear (StrSplitIter *iter) g_free (iter->buf.str); } +/** + * g_typelib_matches_gtype_name_prefix: + * @typelib: TODO + * @gtype_name: TODO + * + * TODO + * + * Returns: TODO + */ gboolean g_typelib_matches_gtype_name_prefix (GITypelib *typelib, const gchar *gtype_name) @@ -326,6 +362,15 @@ g_typelib_matches_gtype_name_prefix (GITypelib *typelib, return ret; } +/** + * g_typelib_get_dir_entry_by_error_domain: + * @typelib: TODO + * @error_domain: TODO + * + * TODO + * + * Returns: TODO + */ DirEntry * g_typelib_get_dir_entry_by_error_domain (GITypelib *typelib, GQuark error_domain) @@ -356,6 +401,11 @@ g_typelib_get_dir_entry_by_error_domain (GITypelib *typelib, return NULL; } +/** + * g_typelib_check_sanity: + * + * TODO + */ void g_typelib_check_sanity (void) { @@ -2089,6 +2139,15 @@ prefix_with_context (GError **error, g_free (buf); } +/** + * g_typelib_validate: + * @typelib: TODO + * @error: TODO + * + * TODO + * + * Returns: TODO + */ gboolean g_typelib_validate (GITypelib *typelib, GError **error) @@ -2118,6 +2177,13 @@ g_typelib_validate (GITypelib *typelib, return TRUE; } +/** + * g_typelib_error_quark: + * + * TODO + * + * Returns: TODO + */ GQuark g_typelib_error_quark (void) { @@ -2271,8 +2337,8 @@ _g_typelib_ensure_open (GITypelib *typelib) * pointed to by @typelib will be automatically g_free()d when the * repository is destroyed. * - * Return value: the new #GITypelib - **/ + * Returns: the new #GITypelib + */ GITypelib * g_typelib_new_from_memory (guint8 *memory, gsize len, @@ -2300,8 +2366,8 @@ g_typelib_new_from_memory (guint8 *memory, * * Creates a new #GITypelib from a memory location. * - * Return value: the new #GITypelib - **/ + * Returns: the new #GITypelib + */ GITypelib * g_typelib_new_from_const_memory (const guchar *memory, gsize len, @@ -2328,8 +2394,8 @@ g_typelib_new_from_const_memory (const guchar *memory, * * Creates a new #GITypelib from a #GMappedFile. * - * Return value: the new #GITypelib - **/ + * Returns: the new #GITypelib + */ GITypelib * g_typelib_new_from_mapped_file (GMappedFile *mfile, GError **error) @@ -2355,7 +2421,7 @@ g_typelib_new_from_mapped_file (GMappedFile *mfile, * @typelib: a #GITypelib * * Free a #GITypelib. - **/ + */ void g_typelib_free (GITypelib *typelib) { @@ -2372,6 +2438,14 @@ g_typelib_free (GITypelib *typelib) g_slice_free (GITypelib, typelib); } +/** + * g_typelib_get_namespace: + * @typelib: TODO + * + * TODO + * + * Returns: TODO + */ const gchar * g_typelib_get_namespace (GITypelib *typelib) { @@ -2386,8 +2460,8 @@ g_typelib_get_namespace (GITypelib *typelib) * * Loads a symbol from #GITypelib. * - * Return value: #TRUE on success - **/ + * Returns: #TRUE on success + */ gboolean g_typelib_symbol (GITypelib *typelib, const char *symbol_name, gpointer *symbol) { diff --git a/girepository/gitypelib.h b/girepository/gitypelib.h index 52c5c400..0726bf19 100644 --- a/girepository/gitypelib.h +++ b/girepository/gitypelib.h @@ -31,6 +31,19 @@ G_BEGIN_DECLS +/** + * SECTION:gitypelib + * @title: gitypelib + * @short_description: TODO + * + * TODO + */ + +/** + * GITypelib: + * + * TODO + */ typedef struct _GITypelib GITypelib; GITypelib * g_typelib_new_from_memory (guint8 *memory, diff --git a/girepository/gitypes.h b/girepository/gitypes.h index 660a98f9..cb8cb344 100644 --- a/girepository/gitypes.h +++ b/girepository/gitypes.h @@ -29,7 +29,9 @@ G_BEGIN_DECLS +#ifndef __GTK_DOC_IGNORE__ typedef struct _GIBaseInfoStub GIBaseInfo; +#endif /** * GICallableInfo: @@ -47,6 +49,25 @@ typedef GIBaseInfo GICallableInfo; typedef GIBaseInfo GIFunctionInfo; /** + * SECTION:gicallbackinfo + * @title: GICallbackInfo + * @short_description: Struct representing a callback + * + * GICallbackInfo represents a callback. + * + * <refsect1 id="gi-gicallbackinfo.struct-hierarchy" role="struct_hierarchy"> + * <title role="struct_hierarchy.title">Struct hierarchy</title> + * <synopsis> + * <link linkend="gi-GIBaseInfo">GIBaseInfo</link> + * +----<link linkend="gi-GICallableInfo">GICallableInfo</link> + * +----GIFunctionInfo + * +----<link linkend="gi-GISignalInfo">GISignalInfo</link> + * +----<link linkend="gi-GIVFuncInfo">GIVFuncInfo</link> + * </synopsis> + * </refsect1> + */ + +/** * GICallbackInfo: * * Represents a callback, eg arguments and return value. @@ -103,6 +124,22 @@ typedef GIBaseInfo GIInterfaceInfo; typedef GIBaseInfo GIConstantInfo; /** + * SECTION:givalueinfo + * @title: GIValueInfo + * @short_description: Struct representing a value + * + * GIValueInfo represents a value. + * + * <refsect1 id="gi-givalueinfo.struct-hierarchy" role="struct_hierarchy"> + * <title role="struct_hierarchy.title">Struct hierarchy</title> + * <synopsis> + * <link linkend="gi-GIBaseInfo">GIBaseInfo</link> + * +----GIValueInfo + * </synopsis> + * </refsect1> + */ + +/** * GIValueInfo: * * Represents a enum value of a #GIEnumInfo. @@ -158,12 +195,7 @@ typedef GIBaseInfo GITypeInfo; */ typedef struct _GIUnresolvedInfo GIUnresolvedInfo; -/** - * GIArgument: - * - * Stores an argument of varying type - */ -typedef union +union _GIArgument { gboolean v_boolean; gint8 v_int8; @@ -186,7 +218,35 @@ typedef union gsize v_size; gchar * v_string; gpointer v_pointer; -} GIArgument; +}; + +/** + * GIArgument: + * @v_boolean: TODO + * @v_int8: TODO + * @v_uint8: TODO + * @v_int16: TODO + * @v_uint16: TODO + * @v_int32: TODO + * @v_uint32: TODO + * @v_int64: TODO + * @v_uint64: TODO + * @v_float: TODO + * @v_double: TODO + * @v_short: TODO + * @v_ushort: TODO + * @v_int: TODO + * @v_uint: TODO + * @v_long: TODO + * @v_ulong: TODO + * @v_ssize: TODO + * @v_size: TODO + * @v_string: TODO + * @v_pointer: TODO + * + * Stores an argument of varying type + */ +typedef union _GIArgument GIArgument; /** * GIInfoType: @@ -200,6 +260,7 @@ typedef union * @GI_INFO_TYPE_OBJECT: object, see #GIObjectInfo * @GI_INFO_TYPE_INTERFACE: interface, see #GIInterfaceInfo * @GI_INFO_TYPE_CONSTANT: contant, see #GIConstantInfo + * @GI_INFO_TYPE_INVALID_0: deleted, used to be GI_INFO_TYPE_ERROR_DOMAIN. * @GI_INFO_TYPE_UNION: union, see #GIUnionInfo * @GI_INFO_TYPE_VALUE: enum value, see #GIValueInfo * @GI_INFO_TYPE_SIGNAL: signal, see #GISignalInfo @@ -209,7 +270,7 @@ typedef union * @GI_INFO_TYPE_ARG: argument of a function or callback, see #GIArgInfo * @GI_INFO_TYPE_TYPE: type information, see #GITypeInfo * @GI_INFO_TYPE_UNRESOLVED: unresolved type, a type which is not present in - * the typelib, or any of its dependencies. + * the typelib, or any of its dependencies. * * The type of a GIBaseInfo struct. */ @@ -225,7 +286,7 @@ typedef enum GI_INFO_TYPE_OBJECT, GI_INFO_TYPE_INTERFACE, GI_INFO_TYPE_CONSTANT, - GI_INFO_TYPE_INVALID_0, /* 10 */ /* DELETED - used to be ERROR_DOMAIN */ + GI_INFO_TYPE_INVALID_0, /* 10 */ GI_INFO_TYPE_UNION, GI_INFO_TYPE_VALUE, GI_INFO_TYPE_SIGNAL, @@ -319,17 +380,17 @@ typedef enum { * @GI_TYPE_TAG_UINT64: 64-bit unsigned integer * @GI_TYPE_TAG_FLOAT: float * @GI_TYPE_TAG_DOUBLE: double floating point - * @GI_TYPE_TAG_UNICHAR: Unicode character * @GI_TYPE_TAG_GTYPE: a #GType * @GI_TYPE_TAG_UTF8: a UTF-8 encoded string * @GI_TYPE_TAG_FILENAME: a filename, encoded in the same encoding - * as the native filesystem is using. + * as the native filesystem is using. * @GI_TYPE_TAG_ARRAY: an array * @GI_TYPE_TAG_INTERFACE: an extended interface object * @GI_TYPE_TAG_GLIST: a #GList * @GI_TYPE_TAG_GSLIST: a #GSList * @GI_TYPE_TAG_GHASH: a #GHashTable * @GI_TYPE_TAG_ERROR: a #GError + * @GI_TYPE_TAG_UNICHAR: Unicode character * * The type tag of a #GITypeInfo. */ @@ -359,12 +420,17 @@ typedef enum { GI_TYPE_TAG_ERROR = 20, /* Another basic type */ GI_TYPE_TAG_UNICHAR = 21 - /* Note - there is only room currently for 32 tags. - * See docs/typelib-format.txt SimpleTypeBlob definition */ + /* Note - there is currently only room for 32 tags */ } GITypeTag; +/** + * GI_TYPE_TAG_N_TYPES: + * + * TODO + */ #define GI_TYPE_TAG_N_TYPES (GI_TYPE_TAG_UNICHAR+1) +#ifndef __GTK_DOC_IGNORE__ /* These were removed and no longer appear in the typelib; * instead, the machine-specific versions like INT32 are * always used. @@ -372,6 +438,7 @@ typedef enum { #define GI_TYPE_TAG_SHORT GI_TYPE_TAG_SHORT_WAS_REMOVED #define GI_TYPE_TAG_INT GI_TYPE_TAG_INT_WAS_REMOVED #define GI_TYPE_TAG_LONG GI_TYPE_TAG_LONG_WAS_REMOVED +#endif /** * GIArrayType: @@ -442,10 +509,12 @@ typedef enum } GIFunctionInfoFlags; #ifndef __GI_SCANNER__ +#ifndef __GTK_DOC_IGNORE__ /* backwards compatibility */ typedef GIArgument GArgument; typedef struct _GITypelib GTypelib; #endif +#endif G_END_DECLS diff --git a/girepository/giunioninfo.c b/girepository/giunioninfo.c index 95b71123..8ae1e915 100644 --- a/girepository/giunioninfo.c +++ b/girepository/giunioninfo.c @@ -28,8 +28,8 @@ /** * SECTION:giunioninfo - * @Short_description: Struct representing a union. - * @Title: GIUnionInfo + * @title: GIUnionInfo + * @short_description: Struct representing a union. * * GIUnionInfo represents a union type. * @@ -147,7 +147,7 @@ g_union_info_is_discriminated (GIUnionInfo *info) } /** - * g_union_info_get_discrimintor_offset: + * g_union_info_get_discriminator_offset: * @info: a #GIUnionInfo * * Returns offset of the discriminator field in the structure. diff --git a/girepository/giunioninfo.h b/girepository/giunioninfo.h index 83696f76..5359346a 100644 --- a/girepository/giunioninfo.h +++ b/girepository/giunioninfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_UNION_INFO + * @info: an info structure + * + * Checks if @info is a #GIUnionInfo. + */ #define GI_IS_UNION_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_UNION) diff --git a/girepository/givfuncinfo.c b/girepository/givfuncinfo.c index 9d6ea39d..eaf523d2 100644 --- a/girepository/givfuncinfo.c +++ b/girepository/givfuncinfo.c @@ -30,8 +30,8 @@ /** * SECTION:givfuncinfo - * @Short_description: Struct representing a virtual function - * @Title: GIVFuncInfo + * @title: GIVFuncInfo + * @short_description: Struct representing a virtual function * * GIVfuncInfo represents a virtual function. A property belongs to * either a #GIObjectInfo or a #GIInterfaceInfo. diff --git a/girepository/givfuncinfo.h b/girepository/givfuncinfo.h index d8a8533b..f22517a6 100644 --- a/girepository/givfuncinfo.h +++ b/girepository/givfuncinfo.h @@ -31,6 +31,12 @@ G_BEGIN_DECLS +/** + * GI_IS_VFUNC_INFO + * @info: an info structure + * + * Checks if @info is a #GIVfuncInfo. + */ #define GI_IS_VFUNC_INFO(info) \ (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_VFUNC) |