From 458cc700ce060c7dabe185744b8f988463e115d9 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 8 Nov 2023 23:36:19 +0000 Subject: [PATCH] girepository: Update docs for GIVFuncInfo for gi-docgen Move the SECTION into the struct docs, update the documentation comment syntax, and add `Since: 2.80` everywhere. Signed-off-by: Philip Withnall Helps: #3155 --- girepository/gitypes.h | 6 +--- girepository/givfuncinfo.c | 57 ++++++++++++++++++++++---------------- girepository/givfuncinfo.h | 6 ++-- 3 files changed, 38 insertions(+), 31 deletions(-) diff --git a/girepository/gitypes.h b/girepository/gitypes.h index 3d382c974..592110dfd 100644 --- a/girepository/gitypes.h +++ b/girepository/gitypes.h @@ -145,11 +145,7 @@ typedef GIBaseInfo GIValueInfo; */ typedef GIBaseInfo GISignalInfo; -/** - * GIVFuncInfo: - * - * Represents a virtual function. - */ +/* Documented in givfuncinfo.c */ typedef GIBaseInfo GIVFuncInfo; /** diff --git a/girepository/givfuncinfo.c b/girepository/givfuncinfo.c index 2dfe73f04..d9de05aa8 100644 --- a/girepository/givfuncinfo.c +++ b/girepository/givfuncinfo.c @@ -34,14 +34,14 @@ #include "givfuncinfo.h" /** - * SECTION:givfuncinfo - * @title: GIVFuncInfo - * @short_description: Struct representing a virtual function + * GIVFuncInfo: * - * GIVfuncInfo represents a virtual function. + * `GIVfuncInfo` represents a virtual function. * * A virtual function is a callable object that belongs to either a - * #GIObjectInfo or a #GIInterfaceInfo. + * [alias@GIRepository.ObjectInfo] or a [alias@GIRepository.InterfaceInfo]. + * + * Since: 2.80 */ GIVFuncInfo * @@ -73,10 +73,13 @@ gi_base_info_find_vfunc (GIRealInfo *rinfo, * gi_vfunc_info_get_flags: * @info: a #GIVFuncInfo * - * Obtain the flags for this virtual function info. See #GIVFuncInfoFlags for - * more information about possible flag values. + * Obtain the flags for this virtual function info. + * + * See [flags@GIRepository.VFuncInfoFlags] for more information about possible + * flag values. * * Returns: the flags + * Since: 2.80 */ GIVFuncInfoFlags gi_vfunc_info_get_flags (GIVFuncInfo *info) @@ -112,9 +115,10 @@ gi_vfunc_info_get_flags (GIVFuncInfo *info) * @info: a #GIVFuncInfo * * Obtain the offset of the function pointer in the class struct. The value - * 0xFFFF indicates that the struct offset is unknown. + * `0xFFFF` indicates that the struct offset is unknown. * - * Returns: the struct offset or 0xFFFF if it's unknown + * Returns: the struct offset or `0xFFFF` if it’s unknown + * Since: 2.80 */ gint gi_vfunc_info_get_offset (GIVFuncInfo *info) @@ -135,10 +139,12 @@ gi_vfunc_info_get_offset (GIVFuncInfo *info) * @info: a #GIVFuncInfo * * Obtain the signal for the virtual function if one is set. + * * The signal comes from the object or interface to which * this virtual function belongs. * - * Returns: (transfer full): the signal or %NULL if none set + * Returns: (transfer full): the signal or `NULL` if none set + * Since: 2.80 */ GISignalInfo * gi_vfunc_info_get_signal (GIVFuncInfo *info) @@ -166,8 +172,9 @@ gi_vfunc_info_get_signal (GIVFuncInfo *info) * * Not all virtuals will have invokers. * - * Returns: (transfer full): the #GIVFuncInfo or %NULL. Free it with - * gi_base_info_unref() when done. + * Returns: (transfer full): the [alias@GIRepository.FunctionInfo] or `NULL`. + * Free it with gi_base_info_unref() when done. + * Since: 2.80 */ GIFunctionInfo * gi_vfunc_info_get_invoker (GIVFuncInfo *info) @@ -202,10 +209,11 @@ gi_vfunc_info_get_invoker (GIVFuncInfo *info) * @implementor_gtype: #GType implementing this virtual function * @error: return location for a #GError * - * This method will look up where inside the type struct of @implementor_gtype - * is the implementation for @info. + * Looks up where inside the type struct of @implementor_gtype is the + * implementation for @info. * - * Returns: address to a function or %NULL if an error happened + * Returns: address to a function or `NULL` if an error happened + * Since: 2.80 */ gpointer gi_vfunc_info_get_address (GIVFuncInfo *vfunc_info, @@ -299,25 +307,26 @@ gi_vfunc_info_get_address (GIVFuncInfo *vfunc_info, * gi_vfunc_info_invoke: (skip) * @info: a #GIVFuncInfo describing the virtual function to invoke * @implementor: #GType of the type that implements this virtual function - * @in_args: (array length=n_in_args): an array of #GIArguments, 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): an array of [struct@GIRepository.Argument]s, + * one for each in parameter of @info. If there are no in parameter, @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 #GIArguments, 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): an array of [struct@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. If the function returns void, @return_value may be - * %NULL - * @error: return location for detailed error information, or %NULL + * `NULL` + * @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. * - * Returns: %TRUE if the function has been invoked, %FALSE if an + * Returns: true if the function has been invoked, false if an * error occurred. + * Since: 2.80 */ gboolean gi_vfunc_info_invoke (GIVFuncInfo *info, diff --git a/girepository/givfuncinfo.h b/girepository/givfuncinfo.h index 2fb67a78e..fce453d48 100644 --- a/girepository/givfuncinfo.h +++ b/girepository/givfuncinfo.h @@ -33,10 +33,12 @@ G_BEGIN_DECLS /** - * GI_IS_VFUNC_INFO + * GI_IS_VFUNC_INFO: * @info: an info structure * - * Checks if @info is a #GIVfuncInfo. + * Checks if @info is a [struct@GIRepository.VFuncInfo]. + * + * Since: 2.80 */ #define GI_IS_VFUNC_INFO(info) \ (gi_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_VFUNC)