mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-09 19:06:15 +01:00
gifunctioninfo: Port documentation to gi-docgen and update
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
parent
a7199e18fd
commit
99a9276594
@ -35,17 +35,17 @@
|
||||
#include "gifunctioninfo.h"
|
||||
|
||||
/**
|
||||
* SECTION:gifunctioninfo
|
||||
* @title: GIFunctionInfo
|
||||
* @short_description: Struct representing a function
|
||||
* GIFunctionInfo:
|
||||
*
|
||||
* GIFunctionInfo represents a function, method or constructor.
|
||||
* `GIFunctionInfo` represents a function, method or constructor.
|
||||
*
|
||||
* To find out what kind of entity a #GIFunctionInfo represents, call
|
||||
* gi_function_info_get_flags().
|
||||
* To find out what kind of entity a `GIFunctionInfo` represents, call
|
||||
* [method@GIRepository.FunctionInfo.get_flags].
|
||||
*
|
||||
* See also #GICallableInfo for information on how to retreive arguments and
|
||||
* other metadata.
|
||||
* See also [class@GIRepository.CallableInfo] for information on how to retrieve
|
||||
* arguments and other metadata.
|
||||
*
|
||||
* Since: 2.80
|
||||
*/
|
||||
|
||||
GIFunctionInfo *
|
||||
@ -77,11 +77,13 @@ gi_base_info_find_method (GIBaseInfo *base,
|
||||
* gi_function_info_get_symbol:
|
||||
* @info: a #GIFunctionInfo
|
||||
*
|
||||
* Obtain the symbol of the function. The symbol is the name of the
|
||||
* exported function, suitable to be used as an argument to
|
||||
* g_module_symbol().
|
||||
* Obtain the symbol of the function.
|
||||
*
|
||||
* The symbol is the name of the exported function, suitable to be used as an
|
||||
* argument to [method@GModule.Module.symbol].
|
||||
*
|
||||
* Returns: the symbol
|
||||
* Since: 2.80
|
||||
*/
|
||||
const gchar *
|
||||
gi_function_info_get_symbol (GIFunctionInfo *info)
|
||||
@ -102,9 +104,10 @@ gi_function_info_get_symbol (GIFunctionInfo *info)
|
||||
* gi_function_info_get_flags:
|
||||
* @info: a #GIFunctionInfo
|
||||
*
|
||||
* Obtain the #GIFunctionInfoFlags for the @info.
|
||||
* Obtain the [type@GIRepository.FunctionInfoFlags] for the @info.
|
||||
*
|
||||
* Returns: the flags
|
||||
* Since: 2.80
|
||||
*/
|
||||
GIFunctionInfoFlags
|
||||
gi_function_info_get_flags (GIFunctionInfo *info)
|
||||
@ -147,13 +150,15 @@ gi_function_info_get_flags (GIFunctionInfo *info)
|
||||
* gi_function_info_get_property:
|
||||
* @info: a #GIFunctionInfo
|
||||
*
|
||||
* Obtain the property associated with this #GIFunctionInfo.
|
||||
* Only #GIFunctionInfo with the flag %GI_FUNCTION_IS_GETTER or
|
||||
* %GI_FUNCTION_IS_SETTER have a property set. For other cases,
|
||||
* %NULL will be returned.
|
||||
* Obtain the property associated with this `GIFunctionInfo`.
|
||||
*
|
||||
* Returns: (transfer full): the property or %NULL if not set. Free it with
|
||||
* gi_base_info_unref() when done.
|
||||
* Only `GIFunctionInfo`s with the flag `GI_FUNCTION_IS_GETTER` or
|
||||
* `GI_FUNCTION_IS_SETTER` have a property set. For other cases,
|
||||
* `NULL` will be returned.
|
||||
*
|
||||
* Returns: (transfer full) (nullable): The property or `NULL` if not set. Free
|
||||
* it with [method@GIRepository.BaseInfo.unref] when done.
|
||||
* Since: 2.80
|
||||
*/
|
||||
GIPropertyInfo *
|
||||
gi_function_info_get_property (GIFunctionInfo *info)
|
||||
@ -187,12 +192,14 @@ gi_function_info_get_property (GIFunctionInfo *info)
|
||||
* gi_function_info_get_vfunc:
|
||||
* @info: a #GIFunctionInfo
|
||||
*
|
||||
* Obtain the virtual function associated with this #GIFunctionInfo.
|
||||
* Only #GIFunctionInfo with the flag %GI_FUNCTION_WRAPS_VFUNC has
|
||||
* a virtual function set. For other cases, %NULL will be returned.
|
||||
* Obtain the virtual function associated with this `GIFunctionInfo`.
|
||||
*
|
||||
* Returns: (transfer full): the virtual function or %NULL if not set.
|
||||
* Free it by calling gi_base_info_unref() when done.
|
||||
* Only `GIFunctionInfo`s with the flag `GI_FUNCTION_WRAPS_VFUNC` have
|
||||
* a virtual function set. For other cases, `NULL` will be returned.
|
||||
*
|
||||
* Returns: (transfer full) (nullable): The virtual function or `NULL` if not
|
||||
* set. Free it by calling [method@GIRepository.BaseInfo.unref] when done.
|
||||
* Since: 2.80
|
||||
*/
|
||||
GIVFuncInfo *
|
||||
gi_function_info_get_vfunc (GIFunctionInfo *info)
|
||||
@ -214,9 +221,10 @@ gi_function_info_get_vfunc (GIFunctionInfo *info)
|
||||
/**
|
||||
* gi_invoke_error_quark:
|
||||
*
|
||||
* TODO
|
||||
* Get the error quark which represents [type@GIRepository.InvokeError].
|
||||
*
|
||||
* Returns: TODO
|
||||
* Returns: error quark
|
||||
* Since: 2.80
|
||||
*/
|
||||
GQuark
|
||||
gi_invoke_error_quark (void)
|
||||
@ -230,27 +238,30 @@ gi_invoke_error_quark (void)
|
||||
/**
|
||||
* gi_function_info_invoke: (skip)
|
||||
* @info: a #GIFunctionInfo describing the function to invoke
|
||||
* @in_args: (array length=n_in_args): an array of #GIArgument<!-- -->s, one for each in
|
||||
* parameter of @info. If there are no in parameter, @in_args
|
||||
* can be %NULL
|
||||
* @in_args: (array length=n_in_args) (nullable): An array of
|
||||
* [type@GIRepository.Argument]s, one for each ‘in’ parameter of @info. If
|
||||
* there are no ‘in’ parameters, @in_args can be `NULL`.
|
||||
* @n_in_args: the length of the @in_args array
|
||||
* @out_args: (array length=n_out_args): an array of #GIArgument<!-- -->s, one for each out
|
||||
* parameter of @info. If there are no out parameters, @out_args
|
||||
* may be %NULL
|
||||
* @out_args: (array length=n_out_args) (nullable): An array of
|
||||
* [type@GIRepository.Argument]s, one for each ‘out’ parameter of @info. If
|
||||
* there are no ‘out’ parameters, @out_args may be `NULL`.
|
||||
* @n_out_args: the length of the @out_args array
|
||||
* @return_value: return location for the return value of the
|
||||
* function.
|
||||
* @error: return location for detailed error information, or %NULL
|
||||
* @return_value: (out caller-allocates) (not optional): return location for the
|
||||
* return value of the function.
|
||||
* @error: return location for detailed error information, or `NULL`
|
||||
*
|
||||
* Invokes the function described in @info with the given
|
||||
* arguments. Note that inout parameters must appear in both
|
||||
* argument lists. This function uses dlsym() to obtain a pointer
|
||||
* to the function, so the library or shared object containing the
|
||||
* described function must either be linked to the caller, or must
|
||||
* have been g_module_symbol()<!-- -->ed before calling this function.
|
||||
* arguments.
|
||||
*
|
||||
* Returns: %TRUE if the function has been invoked, %FALSE if an
|
||||
* Note that ‘inout’ parameters must appear in both argument lists. This
|
||||
* function uses [`dlsym()`](man:dlsym(3)) to obtain a pointer to the function,
|
||||
* so the library or shared object containing the described function must either
|
||||
* be linked to the caller, or must have been loaded with
|
||||
* [method@GModule.Module.symbol] before calling this function.
|
||||
*
|
||||
* Returns: `TRUE` if the function has been invoked, `FALSE` if an
|
||||
* error occurred.
|
||||
* Since: 2.80
|
||||
*/
|
||||
gboolean
|
||||
gi_function_info_invoke (GIFunctionInfo *info,
|
||||
|
||||
@ -33,10 +33,12 @@
|
||||
G_BEGIN_DECLS
|
||||
|
||||
/**
|
||||
* GI_IS_FUNCTION_INFO
|
||||
* GI_IS_FUNCTION_INFO:
|
||||
* @info: an info structure
|
||||
*
|
||||
* Checks if @info is a #GIFunctionInfo.
|
||||
* Checks if @info is a [class@GIRepository.FunctionInfo].
|
||||
*
|
||||
* Since: 2.80
|
||||
*/
|
||||
#define GI_IS_FUNCTION_INFO(info) \
|
||||
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_FUNCTION)
|
||||
@ -57,7 +59,9 @@ GIVFuncInfo * gi_function_info_get_vfunc (GIFunctionInfo *info);
|
||||
/**
|
||||
* GI_INVOKE_ERROR:
|
||||
*
|
||||
* TODO
|
||||
* Type quark function for [enum@GIRepository.InvokeError].
|
||||
*
|
||||
* Since: 2.80
|
||||
*/
|
||||
#define GI_INVOKE_ERROR (gi_invoke_error_quark ())
|
||||
|
||||
@ -66,16 +70,17 @@ GQuark gi_invoke_error_quark (void);
|
||||
|
||||
/**
|
||||
* GIInvokeError:
|
||||
* @GI_INVOKE_ERROR_FAILED: invokation failed, unknown error.
|
||||
* @GI_INVOKE_ERROR_SYMBOL_NOT_FOUND: symbol couldn't be found in any of the
|
||||
* @GI_INVOKE_ERROR_FAILED: invocation failed, unknown error.
|
||||
* @GI_INVOKE_ERROR_SYMBOL_NOT_FOUND: symbol couldn’t be found in any of the
|
||||
* libraries associated with the typelib of the function.
|
||||
* @GI_INVOKE_ERROR_ARGUMENT_MISMATCH: the arguments provided didn't match
|
||||
* the expected arguments for the functions type signature.
|
||||
* @GI_INVOKE_ERROR_ARGUMENT_MISMATCH: the arguments provided didn’t match
|
||||
* the expected arguments for the function’s type signature.
|
||||
*
|
||||
* An error occuring while invoking a function via
|
||||
* gi_function_info_invoke().
|
||||
* An error occurring while invoking a function via
|
||||
* [method@GIRepository.FunctionInfo.invoke].
|
||||
*
|
||||
* Since: 2.80
|
||||
*/
|
||||
|
||||
typedef enum
|
||||
{
|
||||
GI_INVOKE_ERROR_FAILED,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user