luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 03:16:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

gistructinfo: 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-13 13:25:33 +00:00
parent 4f5ac0f997
commit 05d4613483
2 changed files with 45 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
girepository/gistructinfo.c
View File

@ -35,13 +35,13 @@
#include "gistructinfo.h"
/**
* SECTION:gistructinfo
* @title: GIStructInfo
* @short_description: Struct representing a C structure
* GIStructInfo:
*
* GIStructInfo represents a generic C structure type.
* `GIStructInfo` represents a generic C structure type.
*
* A structure has methods and fields.
*
* Since: 2.80
*/
/**
@ -51,6 +51,7 @@
* Obtain the number of fields this structure has.
*
* Returns: number of fields
* Since: 2.80
*/
guint
gi_struct_info_get_n_fields (GIStructInfo *info)
@ -68,7 +69,8 @@ gi_struct_info_get_n_fields (GIStructInfo *info)
*
* Obtain the offset of the specified field.
*
* Returns: field offset in bytes
* Returns: field offset, in bytes
* Since: 2.80
*/
static gint32
gi_struct_get_field_offset (GIStructInfo *info,
@ -97,8 +99,9 @@ gi_struct_get_field_offset (GIStructInfo *info,
*
* Obtain the type information for field with specified index.
*
* Returns: (transfer full): the #GIFieldInfo, free it with gi_base_info_unref()
* when done.
* Returns: (transfer full): The [class@GIRepository.FieldInfo]. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFieldInfo *
gi_struct_info_get_field (GIStructInfo *info,
@ -117,9 +120,10 @@ gi_struct_info_get_field (GIStructInfo *info,
*
* Obtain the type information for field named @name.
*
* Returns: (transfer full) (nullable): The [class@GIRepository.FieldInfo], or
* `NULL` if not found. Free it with [method@GIRepository.BaseInfo.unref] when
* done.
* Since: 2.80
* Returns: (transfer full): the #GIFieldInfo or %NULL if not found,
* free it with gi_base_info_unref() when done.
*/
GIFieldInfo *
gi_struct_info_find_field (GIStructInfo *info,
@ -159,6 +163,7 @@ gi_struct_info_find_field (GIStructInfo *info,
* Obtain the number of methods this structure has.
*
* Returns: number of methods
* Since: 2.80
*/
guint
gi_struct_info_get_n_methods (GIStructInfo *info)
@ -176,8 +181,9 @@ gi_struct_info_get_n_methods (GIStructInfo *info)
*
* Obtain the type information for method with specified index.
*
* Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref()
* when done.
* Returns: (transfer full): The [class@GIRepository.FunctionInfo]. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_struct_info_get_method (GIStructInfo *info,
@ -200,8 +206,10 @@ gi_struct_info_get_method (GIStructInfo *info,
*
* Obtain the type information for method named @name.
*
* Returns: (transfer full): the #GIFunctionInfo, free it with gi_base_info_unref()
* when done.
* Returns: (transfer full) (nullable): The [class@GIRepository.FunctionInfo],
* or `NULL` if none was found. Free it with
* [method@GIRepository.BaseInfo.unref] when done.
* Since: 2.80
*/
GIFunctionInfo *
gi_struct_info_find_method (GIStructInfo *info,
@ -221,7 +229,8 @@ gi_struct_info_find_method (GIStructInfo *info,
*
* Obtain the total size of the structure.
*
* Returns: size of the structure in bytes
* Returns: size of the structure, in bytes
* Since: 2.80
*/
gsize
gi_struct_info_get_size (GIStructInfo *info)
@ -238,7 +247,8 @@ gi_struct_info_get_size (GIStructInfo *info)
*
* Obtain the required alignment of the structure.
*
* Returns: required alignment in bytes
* Returns: required alignment, in bytes
* Since: 2.80
*/
gsize
gi_struct_info_get_alignment (GIStructInfo *info)
@ -251,11 +261,13 @@ gi_struct_info_get_alignment (GIStructInfo *info)
/**
* gi_struct_info_is_foreign:
* @info: TODO
* @info: a #GIStructInfo
*
* TODO
* Gets whether the structure is foreign, i.e. if it’s expected to be overridden
* by a native language binding instead of relying of introspected bindings.
*
* Returns: TODO
* Returns: `TRUE` if the structure is foreign
* Since: 2.80
*/
gboolean
gi_struct_info_is_foreign (GIStructInfo *info)
@ -270,11 +282,14 @@ gi_struct_info_is_foreign (GIStructInfo *info)
* gi_struct_info_is_gtype_struct:
* @info: a #GIStructInfo
*
* Return true if this structure represents the "class structure" for some
* #GObject or #GInterface. This function is mainly useful to hide this kind of structure
* from generated public APIs.
* Return true if this structure represents the ‘class structure’ for some
* [class@GObject.Object] or `GInterface`.
*
* Returns: %TRUE if this is a class struct, %FALSE otherwise
* This function is mainly useful to hide this kind of structure from generated
* public APIs.
*
* Returns: `TRUE` if this is a class struct, `FALSE` otherwise
* Since: 2.80
*/
gboolean
gi_struct_info_is_gtype_struct (GIStructInfo *info)
@ -291,8 +306,8 @@ gi_struct_info_is_gtype_struct (GIStructInfo *info)
*
* Retrieves the name of the copy function for @info, if any is set.
*
* Returns: (transfer none) (nullable): the name of the copy function
*
* Returns: (transfer none) (nullable): the name of the copy function, or `NULL`
* if the structure has no copy function
* Since: 2.80
*/
const char *
@ -318,8 +333,8 @@ gi_struct_info_get_copy_function_name (GIStructInfo *info)
*
* Retrieves the name of the free function for @info, if any is set.
*
* Returns: (transfer none) (nullable): the name of the free function
*
* Returns: (transfer none) (nullable): the name of the free function, or `NULL`
* if the structure has no free function
* Since: 2.80
*/
const char *

6
girepository/gistructinfo.h
View File

@ -33,10 +33,12 @@
G_BEGIN_DECLS
/**
* GI_IS_STRUCT_INFO
* GI_IS_STRUCT_INFO:
* @info: an info structure
*
* Checks if @info is a #GIStructInfo.
* Checks if @info is a [class@GIRepository.StructInfo].
*
* Since: 2.80
*/
#define GI_IS_STRUCT_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_STRUCT)