luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-09-20 01:06:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

giarginfo: 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 00:25:20 +00:00
parent 7688965491
commit 54eae78597
2 changed files with 62 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
girepository/giarginfo.c
View File

@ -35,23 +35,24 @@
/* GIArgInfo functions */
/**
* SECTION:giarginfo
* @title: GIArgInfo
* @short_description: Struct representing an argument
* GIArgInfo:
*
* GIArgInfo represents an argument of a callable.
* `GIArgInfo` represents an argument of a callable.
*
* An argument is always part of a #GICallableInfo.
* An argument is always part of a [class@GIRepository.CallableInfo].
*
* Since: 2.80
*/
/**
* gi_arg_info_get_direction:
* @info: a #GIArgInfo
*
* Obtain the direction of the argument. Check #GIDirection for possible
* direction values.
* Obtain the direction of the argument. Check [type@GIRepository.Direction]
* for possible direction values.
*
* Returns: the direction
* Returns: The direction
* Since: 2.80
*/
GIDirection
gi_arg_info_get_direction (GIArgInfo *info)
@ -79,7 +80,8 @@ gi_arg_info_get_direction (GIArgInfo *info)
* Obtain if the argument is a return value. It can either be a
* parameter or a return value.
*
* Returns: %TRUE if it is a return value
* Returns: `TRUE` if it is a return value
* Since: 2.80
*/
gboolean
gi_arg_info_is_return_value (GIArgInfo *info)
@ -100,11 +102,14 @@ gi_arg_info_is_return_value (GIArgInfo *info)
* @info: a #GIArgInfo
*
* Obtain if the argument is a pointer to a struct or object that will
* receive an output of a function. The default assumption for
* %GI_DIRECTION_OUT arguments which have allocation is that the
* callee allocates; if this is %TRUE, then the caller must allocate.
* receive an output of a function.
*
* Returns: %TRUE if caller is required to have allocated the argument
* The default assumption for `GI_DIRECTION_OUT` arguments which have allocation
* is that the callee allocates; if this is `TRUE`, then the caller must
* allocate.
*
* Returns: `TRUE` if caller is required to have allocated the argument
* Since: 2.80
*/
gboolean
gi_arg_info_is_caller_allocates (GIArgInfo *info)
@ -124,10 +129,13 @@ gi_arg_info_is_caller_allocates (GIArgInfo *info)
* gi_arg_info_is_optional:
* @info: a #GIArgInfo
*
* Obtain if the argument is optional. For 'out' arguments this means
* that you can pass %NULL in order to ignore the result.
* Obtain if the argument is optional.
*
* Returns: %TRUE if it is an optional argument
* For ‘out’ arguments this means that you can pass `NULL` in order to ignore
* the result.
*
* Returns: `TRUE` if it is an optional argument
* Since: 2.80
*/
gboolean
gi_arg_info_is_optional (GIArgInfo *info)
@ -147,13 +155,15 @@ gi_arg_info_is_optional (GIArgInfo *info)
* gi_arg_info_may_be_null:
* @info: a #GIArgInfo
*
* Obtain if the type of the argument includes the possibility of %NULL.
* For 'in' values this means that %NULL is a valid value. For 'out'
* values, this means that %NULL may be returned.
* Obtain if the type of the argument includes the possibility of `NULL`.
*
* See also gi_arg_info_is_optional().
* For ‘in’ values this means that `NULL` is a valid value. For ‘out’
* values, this means that `NULL` may be returned.
*
* Returns: %TRUE if the value may be %NULL
* See also [method@GIRepository.ArgInfo.is_optional].
*
* Returns: `TRUE` if the value may be `NULL`
* Since: 2.80
*/
gboolean
gi_arg_info_may_be_null (GIArgInfo *info)
@ -175,7 +185,7 @@ gi_arg_info_may_be_null (GIArgInfo *info)
*
* Obtain if an argument is only useful in C.
*
* Returns: %TRUE if argument is only useful in C.
* Returns: `TRUE` if argument is only useful in C.
* Since: 2.80
*/
gboolean
@ -197,9 +207,10 @@ gi_arg_info_is_skip (GIArgInfo *info)
* @info: a #GIArgInfo
*
* Obtain the ownership transfer for this argument.
* #GITransfer contains a list of possible values.
* [type@GIRepository.Transfer] contains a list of possible values.
*
* Returns: the transfer
* Returns: The transfer
* Since: 2.80
*/
GITransfer
gi_arg_info_get_ownership_transfer (GIArgInfo *info)
@ -224,12 +235,15 @@ gi_arg_info_get_ownership_transfer (GIArgInfo *info)
* gi_arg_info_get_scope:
* @info: a #GIArgInfo
*
* Obtain the scope type for this argument. The scope type explains
* how a callback is going to be invoked, most importantly when
* the resources required to invoke it can be freed.
* #GIScopeType contains a list of possible values.
* Obtain the scope type for this argument.
*
* Returns: the scope type
* The scope type explains how a callback is going to be invoked, most
* importantly when the resources required to invoke it can be freed.
*
* [type@GIRepository.ScopeType] contains a list of possible values.
*
* Returns: The scope type
* Since: 2.80
*/
GIScopeType
gi_arg_info_get_scope (GIArgInfo *info)
@ -252,7 +266,8 @@ gi_arg_info_get_scope (GIArgInfo *info)
* Obtain the index of the user data argument. This is only valid
* for arguments which are callbacks.
*
* Returns: index of the user data argument or -1 if there is none
* Returns: Index of the user data argument or `-1` if there is none
* Since: 2.80
*/
gint
gi_arg_info_get_closure_index (GIArgInfo *info)
@ -272,10 +287,12 @@ gi_arg_info_get_closure_index (GIArgInfo *info)
* gi_arg_info_get_destroy_index:
* @info: a #GIArgInfo
*
* Obtains the index of the #GDestroyNotify argument. This is only valid
* for arguments which are callbacks.
* Obtains the index of the [type@GLib.DestroyNotify] argument. This is only
* valid for arguments which are callbacks.
*
* Returns: index of the #GDestroyNotify argument or -1 if there is none
* Returns: Index of the [type@GLib.DestroyNotify] argument or `-1` if there is
* none
* Since: 2.80
*/
gint
gi_arg_info_get_destroy_index (GIArgInfo *info)
@ -297,9 +314,10 @@ gi_arg_info_get_destroy_index (GIArgInfo *info)
*
* Obtain the type information for @info.
*
* Returns: (transfer full): the #GITypeInfo holding the type
* information for @info, free it with gi_base_info_unref()
* when done.
* Returns: (transfer full): The [class@GIRepository.TypeInfo] holding the type
* information for @info, free it with [method@GIRepository.BaseInfo.unref]
* when done
* Since: 2.80
*/
GITypeInfo *
gi_arg_info_get_type_info (GIArgInfo *info)
@ -318,10 +336,12 @@ gi_arg_info_get_type_info (GIArgInfo *info)
* @type: (out caller-allocates): Initialized with information about type of @info
*
* Obtain information about a the type of given argument @info; this
* function is a variant of gi_arg_info_get_type_info() designed for stack
* allocation.
* function is a variant of [method@GIRepository.ArgInfo.get_type_info] designed
* for stack allocation.
*
* The initialized @type must not be referenced after @info is deallocated.
*
* Since: 2.80
*/
void
gi_arg_info_load_type (GIArgInfo *info,

6
girepository/giarginfo.h
View File

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