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

girffi: 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:03:37 +00:00
parent de558d9384
commit 372ed18253
2 changed files with 79 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
girepository/girffi.c
View File

@ -35,14 +35,6 @@
#include "girepository.h" #include "girepository.h"
#include "girepository-private.h" #include "girepository-private.h"
/**
* SECTION:girffi
* @short_description: TODO
* @title: girffi
*
* TODO
*/
static ffi_type * static ffi_type *
gi_type_tag_get_ffi_type_internal (GITypeTag tag, gi_type_tag_get_ffi_type_internal (GITypeTag tag,
gboolean is_pointer, gboolean is_pointer,
@ -115,12 +107,14 @@ gi_type_tag_get_ffi_type_internal (GITypeTag tag,
/** /**
* gi_type_tag_get_ffi_type: * gi_type_tag_get_ffi_type:
* @type_tag: A #GITypeTag * @type_tag: a #GITypeTag
* @is_pointer: Whether or not this is a pointer type * @is_pointer: whether this is a pointer type
* *
* TODO * Get the `ffi_type` corresponding to @type_tag.
* *
* Returns: A #ffi_type corresponding to the platform default C ABI for @tag and @is_pointer. * Returns: (transfer none): an `ffi_type` corresponding to the platform default
* C ABI for @tag and @is_pointer.
* Since: 2.80
*/ */
ffi_type * ffi_type *
gi_type_tag_get_ffi_type (GITypeTag type_tag, gi_type_tag_get_ffi_type (GITypeTag type_tag,
@ -131,11 +125,13 @@ gi_type_tag_get_ffi_type (GITypeTag type_tag,
/** /**
* gi_type_info_get_ffi_type: * gi_type_info_get_ffi_type:
* @info: A #GITypeInfo * @info: a #GITypeInfo
* *
* TODO * Get the `ffi_type` corresponding to @info.
* *
* Returns: A #ffi_type corresponding to the platform default C ABI for @info. * Returns: (transfer none): a `ffi_type` corresponding to the platform default
* C ABI for @info.
* Since: 2.80
*/ */
ffi_type * ffi_type *
gi_type_info_get_ffi_type (GITypeInfo *info) gi_type_info_get_ffi_type (GITypeInfo *info)
@ -164,12 +160,14 @@ gi_type_info_get_ffi_type (GITypeInfo *info)
/** /**
* gi_callable_info_get_ffi_arg_types: * gi_callable_info_get_ffi_arg_types:
* @callable_info: a callable info from a typelib * @callable_info: a callable info from a typelib
* @n_args_p: (out): The number of arguments * @n_args_p: (out) (optional): the number of arguments returned
* *
* TODO * Get the `ffi_type`s for the arguments of @callable_info.
* *
* Returns: an array of ffi_type*. The array itself * Returns: (transfer container) (array length=n_args_p): an array of
* should be freed using g_free() after use. * `ffi_type*`. The array itself should be freed using [func@GLib.free] after
* use.
* Since: 2.80
*/ */
static ffi_type ** static ffi_type **
gi_callable_info_get_ffi_arg_types (GICallableInfo *callable_info, gi_callable_info_get_ffi_arg_types (GICallableInfo *callable_info,
@ -233,10 +231,11 @@ gi_callable_info_get_ffi_arg_types (GICallableInfo *callable_info,
* gi_callable_info_get_ffi_return_type: * gi_callable_info_get_ffi_return_type:
* @callable_info: a callable info from a typelib * @callable_info: a callable info from a typelib
* *
* Fetches the ffi_type for a corresponding return value of * Fetches the `ffi_type` for a corresponding return value of
* a #GICallableInfo * a [class@GIRepository.CallableInfo].
* *
* Returns: the ffi_type for the return value * Returns: (transfer none): the `ffi_type` for the return value
* Since: 2.80
*/ */
static ffi_type * static ffi_type *
gi_callable_info_get_ffi_return_type (GICallableInfo *callable_info) gi_callable_info_get_ffi_return_type (GICallableInfo *callable_info)
@ -256,18 +255,19 @@ gi_callable_info_get_ffi_return_type (GICallableInfo *callable_info)
/** /**
* gi_function_info_prep_invoker: * gi_function_info_prep_invoker:
* @info: A #GIFunctionInfo * @info: A #GIFunctionInfo
* @invoker: Output invoker structure * @invoker: (out caller-allocates): Output invoker structure
* @error: A #GError * @error: A #GError
* *
* Initialize the caller-allocated @invoker structure with a cache * Initialize the caller-allocated @invoker structure with a cache
* of information needed to invoke the C function corresponding to * of information needed to invoke the C function corresponding to
* @info with the platform's default ABI. * @info with the platform’s default ABI.
* *
* A primary intent of this function is that a dynamic structure allocated * A primary intent of this function is that a dynamic structure allocated
* by a language binding could contain a #GIFunctionInvoker structure * by a language binding could contain a [type@GIRepository.FunctionInvoker]
* inside the binding's function mapping. * structure inside the binding’s function mapping.
* *
* Returns: %TRUE on success, %FALSE otherwise with @error set. * Returns: `TRUE` on success, `FALSE` otherwise with @error set.
* Since: 2.80
*/ */
gboolean gboolean
gi_function_info_prep_invoker (GIFunctionInfo *info, gi_function_info_prep_invoker (GIFunctionInfo *info,
@ -300,18 +300,19 @@ gi_function_info_prep_invoker (GIFunctionInfo *info,
* gi_function_invoker_new_for_address: * gi_function_invoker_new_for_address:
* @addr: The address * @addr: The address
* @info: A #GICallableInfo * @info: A #GICallableInfo
* @invoker: Output invoker structure * @invoker: (out caller-allocates): Output invoker structure
* @error: A #GError * @error: A #GError
* *
* Initialize the caller-allocated @invoker structure with a cache * Initialize the caller-allocated @invoker structure with a cache
* of information needed to invoke the C function corresponding to * of information needed to invoke the C function corresponding to
* @info with the platform's default ABI. * @info with the platform’s default ABI.
* *
* A primary intent of this function is that a dynamic structure allocated * A primary intent of this function is that a dynamic structure allocated
* by a language binding could contain a #GIFunctionInvoker structure * by a language binding could contain a [type@GIRepository.FunctionInvoker]
* inside the binding's function mapping. * structure inside the binding’s function mapping.
* *
* Returns: %TRUE on success, %FALSE otherwise with @error set. * Returns: `TRUE` on success, `FALSE` otherwise with @error set.
* Since: 2.80
*/ */
gboolean gboolean
gi_function_invoker_new_for_address (gpointer addr, gi_function_invoker_new_for_address (gpointer addr,
@ -336,11 +337,14 @@ gi_function_invoker_new_for_address (gpointer addr,
/** /**
* gi_function_invoker_destroy: * gi_function_invoker_destroy:
* @invoker: A #GIFunctionInvoker * @invoker: (transfer none): A #GIFunctionInvoker
* *
* Release all resources allocated for the internals of @invoker; callers * Release all resources allocated for the internals of @invoker.
* are responsible for freeing any resources allocated for the structure *
* Callers are responsible for freeing any resources allocated for the structure
* itself however. * itself however.
*
* Since: 2.80
*/ */
void void
gi_function_invoker_destroy (GIFunctionInvoker *invoker) gi_function_invoker_destroy (GIFunctionInvoker *invoker)
@ -357,14 +361,16 @@ typedef struct {
/** /**
* gi_callable_info_create_closure: * gi_callable_info_create_closure:
* @callable_info: a callable info from a typelib * @callable_info: a callable info from a typelib
* @cif: a ffi_cif structure * @cif: a `ffi_cif` structure
* @callback: the ffi callback * @callback: the ffi callback
* @user_data: data to be passed into the callback * @user_data: data to be passed into the callback
* *
* Prepares a callback for ffi invocation. * Prepares a callback for ffi invocation.
* *
* Returns: the ffi_closure or NULL on error. The return value * Returns: (transfer full) (nullable): the `ffi_closure`, or `NULL` on error.
* should be freed by calling gi_callable_info_destroy_closure(). * The return value should be freed by calling
* [method@GIRepository.CallableInfo.destroy_closure].
* Since: 2.80
*/ */
ffi_closure * ffi_closure *
gi_callable_info_create_closure (GICallableInfo *callable_info, gi_callable_info_create_closure (GICallableInfo *callable_info,
@ -419,7 +425,11 @@ gi_callable_info_create_closure (GICallableInfo *callable_info,
* @callable_info: a callable info from a typelib * @callable_info: a callable info from a typelib
* @closure: ffi closure * @closure: ffi closure
* *
* Gets callable code from ffi_closure prepared by gi_callable_info_create_closure() * Gets callable code from `ffi_closure` prepared by
* [method@GIRepository.CallableInfo.create_closure].
*
* Returns: (transfer none): native address
* Since: 2.80
*/ */
gpointer * gpointer *
gi_callable_info_get_closure_native_address (GICallableInfo *callable_info, gi_callable_info_get_closure_native_address (GICallableInfo *callable_info,
@ -432,9 +442,12 @@ gi_callable_info_get_closure_native_address (GICallableInfo *callable_info,
/** /**
* gi_callable_info_destroy_closure: * gi_callable_info_destroy_closure:
* @callable_info: a callable info from a typelib * @callable_info: a callable info from a typelib
* @closure: ffi closure * @closure: (transfer full): ffi closure
* *
* Frees a ffi_closure returned from gi_callable_info_create_closure() * Frees a `ffi_closure` returned from
* [method@GIRepository.CallableInfo.create_closure].
*
* Since: 2.80
*/ */
void void
gi_callable_info_destroy_closure (GICallableInfo *callable_info, gi_callable_info_destroy_closure (GICallableInfo *callable_info,

40
girepository/girffi.h
View File

@ -34,38 +34,48 @@ G_BEGIN_DECLS
/** /**
* GIFFIClosureCallback: * GIFFIClosureCallback:
* @Param1: TODO * @cif: the `ffi_cif` passed to
* @Param2: TODO * [method@GIRepository.CallableInfo.create_closure]
* @Param3: TODO * @ret: (out caller-allocates): a pointer to the memory used for the function’s
* @Param4: TODO * return value
* @args: a vector of pointers to memory holding the arguments to the function
* @user_data: the user data passed to
* [method@GIRepository.CallableInfo.create_closure]
* *
* TODO * The function which will be called when a closure created with
* [method@GIRepository.CallableInfo.create_closure] is invoked.
*
* The value of @ret is undefined if the function returns `void`.
*
* Since: 2.80
*/ */
typedef void (*GIFFIClosureCallback) (ffi_cif *, typedef void (*GIFFIClosureCallback) (ffi_cif *cif,
void *, void *ret,
void **, void **args,
void *); void *user_data);
/** /**
* GIFunctionInvoker: * GIFunctionInvoker:
* @cif: the cif * @cif: the cif
* @native_address: the native address * @native_address: the native address
* *
* TODO * Structure containing the data necessary to invoke a callable function.
*
* Since: 2.80
*/ */
typedef struct _GIFunctionInvoker GIFunctionInvoker; typedef struct {
struct _GIFunctionInvoker {
ffi_cif cif; ffi_cif cif;
gpointer native_address; gpointer native_address;
/*< private >*/ /*< private >*/
gpointer padding[3]; gpointer padding[3];
}; } GIFunctionInvoker;
/** /**
* GIFFIReturnValue: * GIFFIReturnValue:
* *
* TODO * The type of a return value from a callable invocation closure.
*
* Since: 2.80
*/ */
typedef GIArgument GIFFIReturnValue; typedef GIArgument GIFFIReturnValue;