luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-04 18:26:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

gitypelib: Port documentation to gi-docgen and update

Browse Source 
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 <pwithnall@gnome.org>

Helps: #3155
This commit is contained in:
Philip Withnall 2023-12-14 01:02:42 +00:00
parent 73fe2cbace
commit 5ccb2d7a06
2 changed files with 139 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
girepository/gitypelib-internal.h
View File

@ -36,7 +36,7 @@ G_BEGIN_DECLS
* @short_description: Layout and accessors for typelib * @short_description: Layout and accessors for typelib
* @stability: Stable * @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. * containing reflective information about a GObject library.
* *
* What the typelib describes and the types used are the same for every * 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: * The typelib has the following general format:
* *
* |[<!-- language="C" --> * ```
* typelib ::= header, section-index, directory, blobs, attributes, attributedata * typelib ::= header, section-index, directory, blobs, attributes, attributedata
* *
* directory ::= list of entries * directory ::= list of entries
@ -69,13 +69,15 @@ G_BEGIN_DECLS
* blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union
* attribute ::= offset, key, value * attribute ::= offset, key, value
* attributedata ::= string data for attributes * attributedata ::= string data for attributes
* ]| * ```
* *
* Details * ## Details
* *
* We describe the fragments that make up the typelib in the form of C structs * 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 * (although some fall short of being valid C structs since they contain
* multiple flexible arrays). * multiple flexible arrays).
*
* Since: 2.80
*/ */
/* /*
@ -148,8 +150,11 @@ Changes since 0.1:
/** /**
* GI_IR_MAGIC: * GI_IR_MAGIC:
* *
* Identifying prefix for the typelib. This was inspired by XPCOM, * Identifying prefix for the typelib.
* which in turn borrowed from PNG. *
* This was inspired by XPCOM, which in turn borrowed from PNG.
*
* Since: 2.80
*/ */
#define GI_IR_MAGIC "GOBJ\nMETADATA\r\n\032" #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 * The integral value of this enumeration appears in each "Blob" component of
* a typelib to identify its type. * a typelib to identify its type.
*
* Since: 2.80
*/ */
typedef enum { typedef enum {
BLOB_TYPE_INVALID, 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 * 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. * collection of meta-information, such as the number of entries and dependencies.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
gchar magic[16]; gchar magic[16];
@ -327,6 +336,8 @@ typedef struct {
* @GI_SECTION_DIRECTORY_INDEX: TODO * @GI_SECTION_DIRECTORY_INDEX: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef enum { typedef enum {
GI_SECTION_END = 0, GI_SECTION_END = 0,
@ -342,6 +353,8 @@ typedef enum {
* and may or may not be present in the typelib. Presently, just used * and may or may not be present in the typelib. Presently, just used
* for the directory index. This allows a form of dynamic extensibility * for the directory index. This allows a form of dynamic extensibility
* with different tradeoffs from the format minor version. * with different tradeoffs from the format minor version.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 id; guint32 id;
@ -363,6 +376,8 @@ typedef struct {
* *
* All blobs pointed to by a directory entry start with the same layout for * 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) * the first 8 bytes (the reserved flags may be used by some blob types)
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -382,6 +397,8 @@ typedef struct {
* @tag: A #GITypeTag * @tag: A #GITypeTag
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint reserved : 8; guint reserved : 8;
@ -419,6 +436,8 @@ union _SimpleTypeBlob
* In this case, the integer is actually an offset into the directory (see * 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 * above). Because the header is larger than 2^8=256 bits, all offsets will
* have one of the upper 24 bits set. * have one of the upper 24 bits set.
*
* Since: 2.80
*/ */
typedef union _SimpleTypeBlob SimpleTypeBlob; 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, * 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 * the low byte describes a basic type, otherwise the 32bit number is an
* offset which points to a TypeBlob. * offset which points to a TypeBlob.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 name; guint32 name;
@ -511,6 +532,8 @@ typedef struct {
* @arguments: An array of ArgBlob for the arguments of the function. * @arguments: An array of ArgBlob for the arguments of the function.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
SimpleTypeBlob return_type; SimpleTypeBlob return_type;
@ -539,6 +562,8 @@ typedef struct {
* #CallbackBlob, #SignalBlob. * #CallbackBlob, #SignalBlob.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; /* 1 */ guint16 blob_type; /* 1 */
@ -576,6 +601,8 @@ typedef struct {
* @reserved2: Reserved for future use. * @reserved2: Reserved for future use.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; /* 1 */ guint16 blob_type; /* 1 */
@ -610,6 +637,8 @@ typedef struct {
* the return value type. * the return value type.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; /* 2 */ guint16 blob_type; /* 2 */
@ -629,6 +658,8 @@ typedef struct {
* @interface: Index of the directory entry for the interface. * @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. * If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint8 pointer :1; guint8 pointer :1;
@ -644,6 +675,8 @@ typedef struct {
* @size: TODO * @size: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef union { typedef union {
guint16 length; guint16 length;
@ -669,6 +702,8 @@ typedef union {
* @type: TODO * @type: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 pointer :1; guint16 pointer :1;
@ -696,6 +731,8 @@ typedef struct {
* @type: Describes the type of the list elements. * @type: Describes the type of the list elements.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint8 pointer :1; guint8 pointer :1;
@ -718,6 +755,8 @@ typedef struct {
* @domains: TODO * @domains: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint8 pointer :1; guint8 pointer :1;
@ -739,6 +778,8 @@ typedef struct {
* @value: The numerical value * @value: The numerical value
* *
* Values commonly occur in enums and flags. * Values commonly occur in enums and flags.
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 deprecated : 1; guint32 deprecated : 1;
@ -763,6 +804,8 @@ typedef struct {
* @type: The type of the field. * @type: The type of the field.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 name; guint32 name;
@ -792,6 +835,8 @@ typedef struct {
* type. * type.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -827,6 +872,8 @@ typedef struct {
* the contents of this struct type * the contents of this struct type
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -876,6 +923,8 @@ typedef struct {
* @discriminator_type: Type of the discriminator * @discriminator_type: Type of the discriminator
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -918,6 +967,8 @@ typedef struct {
* @values: TODO * @values: TODO
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -966,6 +1017,8 @@ typedef struct {
* @type: Describes the type of the property. * @type: Describes the type of the property.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 name; guint32 name;
@ -1007,6 +1060,8 @@ typedef struct {
* and the return value type. * and the return value type.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 deprecated : 1; guint16 deprecated : 1;
@ -1056,6 +1111,8 @@ typedef struct {
* the return value type. * the return value type.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 name; guint32 name;
@ -1116,6 +1173,8 @@ typedef struct {
* interfaces. * interfaces.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; /* 7 */ guint16 blob_type; /* 7 */
@ -1176,6 +1235,8 @@ typedef struct {
* interfaces. * interfaces.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -1215,6 +1276,8 @@ typedef struct {
* @reserved2: Reserved for future use. * @reserved2: Reserved for future use.
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint16 blob_type; guint16 blob_type;
@ -1239,6 +1302,8 @@ typedef struct {
* @value: The value of the attribute (also a string) * @value: The value of the attribute (also a string)
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct { typedef struct {
guint32 offset; guint32 offset;
@ -1283,6 +1348,7 @@ void gi_typelib_check_sanity (void);
* TODO * TODO
* *
* Returns: TODO * Returns: TODO
* Since: 2.80
*/ */
#define gi_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)]) #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 * @GI_TYPELIB_ERROR_INVALID_BLOB: a typelib blob is invalid
* *
* A error set while validating the #GITypelib * A error set while validating the #GITypelib
*
* Since: 2.80
*/ */
typedef enum typedef enum
{ {
@ -1310,6 +1378,8 @@ typedef enum
* GI_TYPELIB_ERROR: * GI_TYPELIB_ERROR:
* *
* TODO * TODO
*
* Since: 2.80
*/ */
#define GI_TYPELIB_ERROR (gi_typelib_error_quark ()) #define GI_TYPELIB_ERROR (gi_typelib_error_quark ())
@ -1329,6 +1399,8 @@ AttributeBlob *_attribute_blob_find_first (GIBaseInfo *info,
* GITypelibHashBuilder: * GITypelibHashBuilder:
* *
* TODO * TODO
*
* Since: 2.80
*/ */
typedef struct _GITypelibHashBuilder GITypelibHashBuilder; typedef struct _GITypelibHashBuilder GITypelibHashBuilder;

103
girepository/gitypelib.c
View File

@ -145,12 +145,13 @@ get_type_blob (GITypelib *typelib,
/** /**
* gi_typelib_get_dir_entry: * gi_typelib_get_dir_entry:
* @typelib: TODO * @typelib: a #GITypelib
* @index: TODO * @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 * DirEntry *
gi_typelib_get_dir_entry (GITypelib *typelib, gi_typelib_get_dir_entry (GITypelib *typelib,
@ -183,12 +184,14 @@ get_section_by_id (GITypelib *typelib,
/** /**
* gi_typelib_get_dir_entry_by_name: * gi_typelib_get_dir_entry_by_name:
* @typelib: TODO * @typelib: a #GITypelib
* @name: TODO * @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 * DirEntry *
gi_typelib_get_dir_entry_by_name (GITypelib *typelib, 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: * gi_typelib_get_dir_entry_by_gtype_name:
* @typelib: TODO * @typelib: a #GITypelib
* @gtype_name: TODO * @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 * DirEntry *
gi_typelib_get_dir_entry_by_gtype_name (GITypelib *typelib, 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: * gi_typelib_matches_gtype_name_prefix:
* @typelib: TODO * @typelib: a #GITypelib
* @gtype_name: TODO * @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 gboolean
gi_typelib_matches_gtype_name_prefix (GITypelib *typelib, 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: * gi_typelib_get_dir_entry_by_error_domain:
* @typelib: TODO * @typelib: a #GITypelib
* @error_domain: TODO * @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 * DirEntry *
gi_typelib_get_dir_entry_by_error_domain (GITypelib *typelib, 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: * gi_typelib_check_sanity:
* *
* TODO * Check compile-time sizes of various typelib file format types are as
* expected.
*
* Since: 2.80
*/ */
void void
gi_typelib_check_sanity (void) gi_typelib_check_sanity (void)
@ -2180,12 +2194,14 @@ prefix_with_context (GError **error,
/** /**
* gi_typelib_validate: * gi_typelib_validate:
* @typelib: TODO * @typelib: a #GITypelib
* @error: TODO * @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 gboolean
gi_typelib_validate (GITypelib *typelib, gi_typelib_validate (GITypelib *typelib,
@ -2219,9 +2235,10 @@ gi_typelib_validate (GITypelib *typelib,
/** /**
* gi_typelib_error_quark: * 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 GQuark
gi_typelib_error_quark (void) gi_typelib_error_quark (void)
@ -2240,15 +2257,17 @@ static GSList *library_paths;
* *
* Prepends @directory to the search path that is used to * Prepends @directory to the search path that is used to
* search shared libraries referenced by imported namespaces. * search shared libraries referenced by imported namespaces.
*
* Multiple calls to this function all contribute to the final * Multiple calls to this function all contribute to the final
* list of paths. * list of paths.
* The list of paths is unique and shared for all #GIRepository *
* instances across the process, but it doesn't affect namespaces * The list of paths is unique and shared for all
* imported before the call. * [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 * If the library is not found in the directories configured
* in this way, loading will fall back to the system library * 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. * See the documentation of your dynamic linker for full details.
* *
* Since: 2.80 * Since: 2.80
@ -2379,15 +2398,15 @@ gi_typelib_ensure_open (GITypelib *typelib)
/** /**
* gi_typelib_new_from_memory: (skip) * gi_typelib_new_from_memory: (skip)
* @memory: (array length=len): address of memory chunk containing the typelib * @memory: (array length=len): address of memory chunk containing the typelib
* @len: length of memory chunk containing the typelib * @len: length of memory chunk containing the typelib, in bytes
* @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.
* *
* The memory block pointed to by @typelib will be automatically freed when the * The memory block pointed to by @typelib will be automatically freed when the
* repository is destroyed. * repository is destroyed.
* *
* Returns: (transfer full): the new #GITypelib * Returns: (transfer full): the new [type@GIRepository.Typelib]
* Since: 2.80 * Since: 2.80
*/ */
GITypelib * GITypelib *
@ -2413,11 +2432,11 @@ gi_typelib_new_from_memory (guint8 *memory,
* gi_typelib_new_from_const_memory: (skip) * gi_typelib_new_from_const_memory: (skip)
* @memory: (array length=len): address of memory chunk containing the typelib * @memory: (array length=len): address of memory chunk containing the typelib
* @len: length 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 * Since: 2.80
*/ */
GITypelib * GITypelib *
@ -2445,9 +2464,9 @@ gi_typelib_new_from_const_memory (const guchar *memory,
* the repository is destroyed * the repository is destroyed
* @error: a #GError * @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 * Since: 2.80
*/ */
GITypelib * GITypelib *
@ -2474,7 +2493,7 @@ gi_typelib_new_from_mapped_file (GMappedFile *mfile,
* gi_typelib_free: * gi_typelib_free:
* @typelib: (transfer full): a #GITypelib * @typelib: (transfer full): a #GITypelib
* *
* Free a `GITypelib`. * Free a [type@GIRepository.Typelib].
* *
* Since: 2.80 * Since: 2.80
*/ */
@ -2518,7 +2537,7 @@ gi_typelib_get_namespace (GITypelib *typelib)
* *
* Loads a symbol from a `GITypelib`. * Loads a symbol from a `GITypelib`.
* *
* Returns: true on success * Returns: `TRUE` on success
* Since: 2.80 * Since: 2.80
*/ */
gboolean gboolean