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

girepository/gifunctioninfo.c

@@ -35,17 +35,17 @@
 #include "gifunctioninfo.h"
 
 /**
- * SECTION:gifunctioninfo
+ * GIFunctionInfo:
- * @title: GIFunctionInfo
- * @short_description: Struct representing a function
  *
- * 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
+ * To find out what kind of entity a `GIFunctionInfo` represents, call
- * gi_function_info_get_flags().
+ * [method@GIRepository.FunctionInfo.get_flags].
  *
- * See also #GICallableInfo for information on how to retreive arguments and
+ * See also [class@GIRepository.CallableInfo] for information on how to retrieve
- * other metadata.
+ * 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
+ * Obtain the symbol of the function.
- * exported function, suitable to be used as an argument to
+ *
- * g_module_symbol().
+ * 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.
+ * 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.
  *
- * Returns: (transfer full): the property or %NULL if not set. Free it with
+ * Only `GIFunctionInfo`s with the flag `GI_FUNCTION_IS_GETTER` or
- *   gi_base_info_unref() when done.
+ * `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.
+ * 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.
  *
- * Returns: (transfer full): the virtual function or %NULL if not set.
+ * Only `GIFunctionInfo`s with the flag `GI_FUNCTION_WRAPS_VFUNC` have
- *   Free it by calling gi_base_info_unref() when done.
+ * 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
+ * @in_args: (array length=n_in_args) (nullable): An array of
- *    parameter of @info. If there are no in parameter, @in_args
+ *   [type@GIRepository.Argument]s, one for each ‘in’ parameter of @info. If
- *    can be %NULL
+ *   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
+ * @out_args: (array length=n_out_args) (nullable): An array of
- *    parameter of @info. If there are no out parameters, @out_args
+ *   [type@GIRepository.Argument]s, one for each ‘out’ parameter of @info. If
- *    may be %NULL
+ *   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
+ * @return_value: (out caller-allocates) (not optional): return location for the
- *    function.
+ *   return value of the function.
- * @error: return location for detailed error information, or %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
+ * arguments.
- * 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.
  *
- * 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,

girepository/gifunctioninfo.h

@@ -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_FAILED: invocation failed, unknown error.
- * @GI_INVOKE_ERROR_SYMBOL_NOT_FOUND: symbol couldn't be found in any of the
+ * @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
+ * @GI_INVOKE_ERROR_ARGUMENT_MISMATCH: the arguments provided didn’t match
- *   the expected arguments for the functions type signature.
+ *   the expected arguments for the function’s type signature.
  *
- * An error occuring while invoking a function via
+ * An error occurring while invoking a function via
- * gi_function_info_invoke().
+ * [method@GIRepository.FunctionInfo.invoke].
+ *
+ * Since: 2.80
  */
-
 typedef enum
 {
   GI_INVOKE_ERROR_FAILED,