From 5ccb2d7a06806f13878df9545a6a1591194ffe94 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 14 Dec 2023 01:02:42 +0000 Subject: [PATCH] gitypelib: Port documentation to gi-docgen and update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review and update the documentation, making sure it’s complete, formatted in gi-docgen format, and has all appropriate GIR annotations and `Since:` lines. Signed-off-by: Philip Withnall Helps: #3155 --- girepository/gitypelib-internal.h | 84 ++++++++++++++++++++++-- girepository/gitypelib.c | 103 ++++++++++++++++++------------ 2 files changed, 139 insertions(+), 48 deletions(-) diff --git a/girepository/gitypelib-internal.h b/girepository/gitypelib-internal.h index b02f05044..a83f1ae3c 100644 --- a/girepository/gitypelib-internal.h +++ b/girepository/gitypelib-internal.h @@ -36,7 +36,7 @@ G_BEGIN_DECLS * @short_description: Layout and accessors for typelib * @stability: Stable * - * The "typelib" is a binary, readonly, memory-mappable database + * The ‘typelib’ is a binary, readonly, memory-mappable database * containing reflective information about a GObject library. * * What the typelib describes and the types used are the same for every @@ -60,7 +60,7 @@ G_BEGIN_DECLS * * The typelib has the following general format: * - * |[ + * ``` * typelib ::= header, section-index, directory, blobs, attributes, attributedata * * directory ::= list of entries @@ -69,13 +69,15 @@ G_BEGIN_DECLS * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union * attribute ::= offset, key, value * attributedata ::= string data for attributes - * ]| + * ``` * - * Details + * ## 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). + * + * Since: 2.80 */ /* @@ -148,8 +150,11 @@ Changes since 0.1: /** * GI_IR_MAGIC: * - * Identifying prefix for the typelib. This was inspired by XPCOM, - * which in turn borrowed from PNG. + * Identifying prefix for the typelib. + * + * This was inspired by XPCOM, which in turn borrowed from PNG. + * + * Since: 2.80 */ #define GI_IR_MAGIC "GOBJ\nMETADATA\r\n\032" @@ -170,6 +175,8 @@ Changes since 0.1: * * The integral value of this enumeration appears in each "Blob" component of * a typelib to identify its type. + * + * Since: 2.80 */ typedef enum { BLOB_TYPE_INVALID, @@ -276,6 +283,8 @@ _blob_is_registered_type (GITypelibBlobType blob_type) * * 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. + * + * Since: 2.80 */ typedef struct { gchar magic[16]; @@ -327,6 +336,8 @@ typedef struct { * @GI_SECTION_DIRECTORY_INDEX: TODO * * TODO + * + * Since: 2.80 */ typedef enum { GI_SECTION_END = 0, @@ -342,6 +353,8 @@ 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. + * + * Since: 2.80 */ typedef struct { guint32 id; @@ -363,6 +376,8 @@ typedef struct { * * All blobs pointed to by a directory entry start with the same layout for * the first 8 bytes (the reserved flags may be used by some blob types) + * + * Since: 2.80 */ typedef struct { guint16 blob_type; @@ -382,6 +397,8 @@ typedef struct { * @tag: A #GITypeTag * * TODO + * + * Since: 2.80 */ typedef struct { guint reserved : 8; @@ -419,6 +436,8 @@ union _SimpleTypeBlob * 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. + * + * Since: 2.80 */ typedef union _SimpleTypeBlob SimpleTypeBlob; @@ -466,6 +485,8 @@ typedef union _SimpleTypeBlob SimpleTypeBlob; * 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 * offset which points to a TypeBlob. + * + * Since: 2.80 */ typedef struct { guint32 name; @@ -511,6 +532,8 @@ typedef struct { * @arguments: An array of ArgBlob for the arguments of the function. * * TODO + * + * Since: 2.80 */ typedef struct { SimpleTypeBlob return_type; @@ -539,6 +562,8 @@ typedef struct { * #CallbackBlob, #SignalBlob. * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; /* 1 */ @@ -576,6 +601,8 @@ typedef struct { * @reserved2: Reserved for future use. * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; /* 1 */ @@ -610,6 +637,8 @@ typedef struct { * the return value type. * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; /* 2 */ @@ -629,6 +658,8 @@ typedef struct { * @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. + * + * Since: 2.80 */ typedef struct { guint8 pointer :1; @@ -644,6 +675,8 @@ typedef struct { * @size: TODO * * TODO + * + * Since: 2.80 */ typedef union { guint16 length; @@ -669,6 +702,8 @@ typedef union { * @type: TODO * * TODO + * + * Since: 2.80 */ typedef struct { guint16 pointer :1; @@ -696,6 +731,8 @@ typedef struct { * @type: Describes the type of the list elements. * * TODO + * + * Since: 2.80 */ typedef struct { guint8 pointer :1; @@ -718,6 +755,8 @@ typedef struct { * @domains: TODO * * TODO + * + * Since: 2.80 */ typedef struct { guint8 pointer :1; @@ -739,6 +778,8 @@ typedef struct { * @value: The numerical value * * Values commonly occur in enums and flags. + * + * Since: 2.80 */ typedef struct { guint32 deprecated : 1; @@ -763,6 +804,8 @@ typedef struct { * @type: The type of the field. * * TODO + * + * Since: 2.80 */ typedef struct { guint32 name; @@ -792,6 +835,8 @@ typedef struct { * type. * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; @@ -827,6 +872,8 @@ typedef struct { * the contents of this struct type * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; @@ -876,6 +923,8 @@ typedef struct { * @discriminator_type: Type of the discriminator * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; @@ -918,6 +967,8 @@ typedef struct { * @values: TODO * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; @@ -966,6 +1017,8 @@ typedef struct { * @type: Describes the type of the property. * * TODO + * + * Since: 2.80 */ typedef struct { guint32 name; @@ -1007,6 +1060,8 @@ typedef struct { * and the return value type. * * TODO + * + * Since: 2.80 */ typedef struct { guint16 deprecated : 1; @@ -1056,6 +1111,8 @@ typedef struct { * the return value type. * * TODO + * + * Since: 2.80 */ typedef struct { guint32 name; @@ -1116,6 +1173,8 @@ typedef struct { * interfaces. * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; /* 7 */ @@ -1176,6 +1235,8 @@ typedef struct { * interfaces. * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; @@ -1215,6 +1276,8 @@ typedef struct { * @reserved2: Reserved for future use. * * TODO + * + * Since: 2.80 */ typedef struct { guint16 blob_type; @@ -1239,6 +1302,8 @@ typedef struct { * @value: The value of the attribute (also a string) * * TODO + * + * Since: 2.80 */ typedef struct { guint32 offset; @@ -1283,6 +1348,7 @@ void gi_typelib_check_sanity (void); * TODO * * Returns: TODO + * Since: 2.80 */ #define gi_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)]) @@ -1296,6 +1362,8 @@ void gi_typelib_check_sanity (void); * @GI_TYPELIB_ERROR_INVALID_BLOB: a typelib blob is invalid * * A error set while validating the #GITypelib + * + * Since: 2.80 */ typedef enum { @@ -1310,6 +1378,8 @@ typedef enum * GI_TYPELIB_ERROR: * * TODO + * + * Since: 2.80 */ #define GI_TYPELIB_ERROR (gi_typelib_error_quark ()) @@ -1329,6 +1399,8 @@ AttributeBlob *_attribute_blob_find_first (GIBaseInfo *info, * GITypelibHashBuilder: * * TODO + * + * Since: 2.80 */ typedef struct _GITypelibHashBuilder GITypelibHashBuilder; diff --git a/girepository/gitypelib.c b/girepository/gitypelib.c index 9d75de28c..447de9550 100644 --- a/girepository/gitypelib.c +++ b/girepository/gitypelib.c @@ -145,12 +145,13 @@ get_type_blob (GITypelib *typelib, /** * gi_typelib_get_dir_entry: - * @typelib: TODO - * @index: TODO + * @typelib: a #GITypelib + * @index: index to retrieve * - * TODO + * Get the typelib directory entry at the given @index. * - * Returns: TODO + * Returns: (transfer none): a `DirEntry` + * Since: 2.80 */ DirEntry * gi_typelib_get_dir_entry (GITypelib *typelib, @@ -183,12 +184,14 @@ get_section_by_id (GITypelib *typelib, /** * gi_typelib_get_dir_entry_by_name: - * @typelib: TODO - * @name: TODO + * @typelib: a #GITypelib + * @name: name to look up * - * TODO + * Get the typelib directory entry which has @name. * - * Returns: TODO + * Returns: (transfer none) (nullable): entry corresponding to @name, or `NULL` + * if none was found + * Since: 2.80 */ DirEntry * gi_typelib_get_dir_entry_by_name (GITypelib *typelib, @@ -229,12 +232,15 @@ gi_typelib_get_dir_entry_by_name (GITypelib *typelib, /** * gi_typelib_get_dir_entry_by_gtype_name: - * @typelib: TODO - * @gtype_name: TODO + * @typelib: a #GITypelib + * @gtype_name: name of a [type@GObject.Type] to look up * - * TODO + * Get the typelib directory entry for the [type@GObject.Type] with the given + * @gtype_name. * - * Returns: TODO + * Returns: (transfer none) (nullable): entry corresponding to @gtype_name, or + * `NULL` if none was found + * Since: 2.80 */ DirEntry * gi_typelib_get_dir_entry_by_gtype_name (GITypelib *typelib, @@ -323,12 +329,14 @@ strsplit_iter_clear (StrSplitIter *iter) /** * gi_typelib_matches_gtype_name_prefix: - * @typelib: TODO - * @gtype_name: TODO + * @typelib: a #GITypelib + * @gtype_name: name of a [type@GObject.Type] * - * TODO + * Check whether the symbol prefix for @typelib is a prefix of the given + * @gtype_name. * - * Returns: TODO + * Returns: `TRUE` if the prefix for @typelib prefixes @gtype_name + * Since: 2.80 */ gboolean gi_typelib_matches_gtype_name_prefix (GITypelib *typelib, @@ -377,12 +385,15 @@ gi_typelib_matches_gtype_name_prefix (GITypelib *typelib, /** * gi_typelib_get_dir_entry_by_error_domain: - * @typelib: TODO - * @error_domain: TODO + * @typelib: a #GITypelib + * @error_domain: name of a [type@GLib.Error] domain to look up * - * TODO + * Get the typelib directory entry for the [type@GLib.Error] domain with the + * given @error_domain name. * - * Returns: TODO + * Returns: (transfer none) (nullable): entry corresponding to @error_domain, or + * `NULL` if none was found + * Since: 2.80 */ DirEntry * gi_typelib_get_dir_entry_by_error_domain (GITypelib *typelib, @@ -417,7 +428,10 @@ gi_typelib_get_dir_entry_by_error_domain (GITypelib *typelib, /** * gi_typelib_check_sanity: * - * TODO + * Check compile-time sizes of various typelib file format types are as + * expected. + * + * Since: 2.80 */ void gi_typelib_check_sanity (void) @@ -2180,12 +2194,14 @@ prefix_with_context (GError **error, /** * gi_typelib_validate: - * @typelib: TODO - * @error: TODO + * @typelib: a #GITypelib + * @error: return location for a [type@GLib.Error], or `NULL` * - * TODO + * Check whether @typelib is well-formed, i.e. that the file is not corrupt or + * truncated. * - * Returns: TODO + * Returns: `TRUE` if @typelib is well-formed, `FALSE` otherwise + * Since: 2.80 */ gboolean gi_typelib_validate (GITypelib *typelib, @@ -2219,9 +2235,10 @@ gi_typelib_validate (GITypelib *typelib, /** * gi_typelib_error_quark: * - * TODO + * Get the quark representing the [type@GIRepository.TypelibError] error domain. * - * Returns: TODO + * Returns: quark representing the error domain + * Since: 2.80 */ GQuark gi_typelib_error_quark (void) @@ -2240,15 +2257,17 @@ static GSList *library_paths; * * Prepends @directory to the search path that is used to * search shared libraries referenced by imported namespaces. + * * Multiple calls to this function all contribute to the final * list of paths. - * The list of paths is unique and shared for all #GIRepository - * instances across the process, but it doesn't affect namespaces - * imported before the call. + * + * The list of paths is unique and shared for all + * [class@GIRepository.Repository] instances across the process, but it doesn’t + * affect namespaces imported before the call. * * If the library is not found in the directories configured * in this way, loading will fall back to the system library - * path (ie. LD_LIBRARY_PATH and DT_RPATH in ELF systems). + * path (i.e. `LD_LIBRARY_PATH` and `DT_RPATH` in ELF systems). * See the documentation of your dynamic linker for full details. * * Since: 2.80 @@ -2379,15 +2398,15 @@ gi_typelib_ensure_open (GITypelib *typelib) /** * gi_typelib_new_from_memory: (skip) * @memory: (array length=len): address of memory chunk containing the typelib - * @len: length of memory chunk containing the typelib - * @error: a #GError + * @len: length of memory chunk containing the typelib, in bytes + * @error: a [type@GLib.Error] * - * Creates a new `GITypelib` from a memory location. + * Creates a new [type@GIRepository.Typelib] from a memory location. * * The memory block pointed to by @typelib will be automatically freed when the * repository is destroyed. * - * Returns: (transfer full): the new #GITypelib + * Returns: (transfer full): the new [type@GIRepository.Typelib] * Since: 2.80 */ GITypelib * @@ -2413,11 +2432,11 @@ gi_typelib_new_from_memory (guint8 *memory, * gi_typelib_new_from_const_memory: (skip) * @memory: (array length=len): address of memory chunk containing the typelib * @len: length of memory chunk containing the typelib - * @error: a #GError + * @error: a [type@GLib.Error] * - * Creates a new `GITypelib` from a memory location. + * Creates a new [type@GIRepository.Typelib] from a memory location. * - * Returns: (transfer full): the new #GITypelib + * Returns: (transfer full): the new [type@GIRepository.Typelib] * Since: 2.80 */ GITypelib * @@ -2445,9 +2464,9 @@ gi_typelib_new_from_const_memory (const guchar *memory, * the repository is destroyed * @error: a #GError * - * Creates a new `GITypelib` from a [type@GLib.MappedFile]. + * Creates a new [type@GIRepository.Typelib] from a [type@GLib.MappedFile]. * - * Returns: (transfer full): the new #GITypelib + * Returns: (transfer full): the new [type@GIRepository.Typelib] * Since: 2.80 */ GITypelib * @@ -2474,7 +2493,7 @@ gi_typelib_new_from_mapped_file (GMappedFile *mfile, * gi_typelib_free: * @typelib: (transfer full): a #GITypelib * - * Free a `GITypelib`. + * Free a [type@GIRepository.Typelib]. * * Since: 2.80 */ @@ -2518,7 +2537,7 @@ gi_typelib_get_namespace (GITypelib *typelib) * * Loads a symbol from a `GITypelib`. * - * Returns: true on success + * Returns: `TRUE` on success * Since: 2.80 */ gboolean