[docs] Document GICallableInfo and GIArgInfo

Make docs more consistent and also fix a couple of broken links
2025-02-28 13:12:10 +01:00 · 2010-05-21 18:30:58 -03:00 · 2010-05-21 18:30:58 -03:00 · 9505b6eb44
commit 9505b6eb44
parent 7e2e379388
2 changed files with 129 additions and 22 deletions
--- a/ginfo.c
+++ b/ginfo.c
@ -249,7 +249,7 @@ g_base_info_unref (GIBaseInfo *info)
 * g_base_info_get_type:
 * @info: a #GIBaseInfo
 *
- * Obtains the info type of the GIBaseInfo.
+ * Obtain the info type of the GIBaseInfo.
 *
 * Returns: the info type of @info
 */
@ -264,7 +264,7 @@ g_base_info_get_type (GIBaseInfo *info)
 * g_base_info_get_name:
 * @info: a #GIBaseInfo
 *
- * Obtains the name of the @info. What the name represents depends on
+ * Obtain the name of the @info. What the name represents depends on
 * the #GIInfoType of the @info. For instance for #GIFunctionInfo it is
 * the name of the function.
 *
@ -362,7 +362,7 @@ g_base_info_get_name (GIBaseInfo *info)
 * g_base_info_get_namespace:
 * @info: a #GIBaseInfo
 *
- * Obtains the namespace of @info.
+ * Obtain the namespace of @info.
 *
 * Returns: the namespace
 */
@ -388,7 +388,7 @@ g_base_info_get_namespace (GIBaseInfo *info)
 * g_base_info_is_deprecated:
 * @info: a #GIBaseInfo
 *
- * Obtains whether the @info is represents a metadata which is
+ * Obtain whether the @info is represents a metadata which is
 * deprecated or not.
 *
 * Returns: %TRUE if deprecated
@ -581,7 +581,7 @@ g_base_info_iterate_attributes (GIBaseInfo       *info,
 * g_base_info_get_container:
 * @info: a #GIBaseInfo
 *
- * Obtains the container of the @info. The container is the parent
+ * Obtain the container of the @info. The container is the parent
 * GIBaseInfo. For instance, the parent of a #GIFunctionInfo is an
 * #GIObjectInfo or #GIInterfaceInfo.
 *
@ -597,7 +597,7 @@ g_base_info_get_container (GIBaseInfo *info)
 * g_base_info_get_typelib:
 * @info: a #GIBaseInfo
 *
- * Obtains the typelib this @info belongs to
+ * Obtain the typelib this @info belongs to
 *
 * Returns: (transfer none): the typelib.
 */
@ -648,7 +648,7 @@ g_base_info_equal (GIBaseInfo *info1, GIBaseInfo *info2)
 * g_function_info_get_symbol:
 * @info: a #GIFunctionInfo
 *
- * Obtains the symbol of the function. The symbol is the name of the
+ * 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().
 *
@ -667,7 +667,7 @@ g_function_info_get_symbol (GIFunctionInfo *info)
 * g_function_info_get_flags:
 * @info: a #GIFunctionInfo
 *
- * Obtains the #GIFunctionInfoFlags for the @info.
+ * Obtain the #GIFunctionInfoFlags for the @info.
 *
 * Returns: the flags
 */
@ -706,7 +706,7 @@ g_function_info_get_flags (GIFunctionInfo *info)
 * g_function_info_get_property:
 * @info: a #GIFunctionInfo
 *
- * Obtains 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.
@ -728,7 +728,7 @@ g_function_info_get_property (GIFunctionInfo *info)
 * g_function_info_get_vfunc:
 * @info: a #GIFunctionInfo
 *
- * Obtains 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.
 *
@ -746,6 +746,20 @@ g_function_info_get_vfunc (GIFunctionInfo *info)
 }

 /* GICallableInfo functions */
+
+/**
+ * SECTION:gicallableinfo
+ * @Short_description: Struct representing a callable
+ * @Title: GICallableInfo
+ *
+ * GICallableInfo represents an entity which is callable.
+ * Currently a function (#GIFunctionInfo), virtual function,
+ * (#GIVirtualFunc) or callback (#GICallbackInfo).
+ *
+ * A callable has a list of arguments (#GIArgInfo), a return type,
+ * direction and a flag which decides if it returns null.
+ *
+ */
 static guint32
 signature_offset (GICallableInfo *info)
 {
@ -800,7 +814,7 @@ g_type_info_init (GIBaseInfo *info,
 * g_callable_info_get_return_type:
 * @info: a #GICallableInfo
 *
- * Get the return type of a callable item as a #GITypeInfo.
+ * Obtain the return type of a callable item as a #GITypeInfo.
 *
 * Returns: (transfer full): the #GITypeInfo. Free the struct by calling
 * g_base_info_unref() when done.
@ -822,7 +836,7 @@ g_callable_info_get_return_type (GICallableInfo *info)
 * @info: a #GICallableInfo
 * @type: (out caller-allocates): Initialized with return type of @info
 *
- * Get information about a return value of callable; this
+ * Obtain information about a return value of callable; this
 * function is a variant of g_callable_info_get_return_type() designed for stack
 * allocation.
 *
@ -861,8 +875,8 @@ g_callable_info_may_return_null (GICallableInfo *info)
 * g_callable_info_get_caller_owns:
 * @info: a #GICallableInfo
 *
- * See whether the caller owns the return value
- * of this callable.
+ * See whether the caller owns the return value of this callable.
+ * #GITransfer contains a list of possible transfer values.
 *
 * Returns: %TRUE if the caller owns the return value, %FALSE otherwise.
 */
@ -884,7 +898,7 @@ g_callable_info_get_caller_owns (GICallableInfo *info)
 * g_callable_info_get_n_args:
 * @info: a #GICallableInfo
 *
- * Get the number of arguments (both IN and OUT) for this callable.
+ * Obtain the number of arguments (both IN and OUT) for this callable.
 *
 * Returns: The number of arguments this callable expects.
 */
@ -906,7 +920,7 @@ g_callable_info_get_n_args (GICallableInfo *info)
 * @info: a #GICallableInfo
 * @n: the argument index to fetch
 *
- * Get information about a particular argument of this callable.
+ * Obtain information about a particular argument of this callable.
 *
 * Returns: (transfer full): the #GIArgInfo. Free it with
 * g_base_info_unref() when done.
@ -931,7 +945,7 @@ g_callable_info_get_arg (GICallableInfo *info,
 * @n: the argument index to fetch
 * @arg: (out caller-allocates): Initialize with argument number @n
 *
- * Get information about a particular argument of this callable; this
+ * Obtain information about a particular argument of this callable; this
 * function is a variant of g_callable_info_get_arg() designed for stack
 * allocation.
 *
@ -953,6 +967,27 @@ g_callable_info_load_arg (GICallableInfo *info,
 }

 /* GIArgInfo function */
+
+/**
+ * SECTION:giarginfo
+ * @Short_description: Struct representing an argument
+ * @Title: GIArgInfo
+ *
+ * GIArgInfo represents an argument. An argument is always
+ * part of a #GICallableInfo.
+ *
+ *
+ */
+
+/**
+ * g_arg_info_get_direction:
+ * @info: a #GIArgInfo
+ *
+ * Obtain the direction of the argument. Check #GIDirection for possible
+ * direction values.
+ *
+ * Returns: the direction
+ */
 GIDirection
 g_arg_info_get_direction (GIArgInfo *info)
 {
@ -967,6 +1002,15 @@ g_arg_info_get_direction (GIArgInfo *info)
    return GI_DIRECTION_IN;
 }

+/**
+ * g_arg_info_is_return_value:
+ * @info: a #GIArgInfo
+ *
+ * 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
+ */
 gboolean
 g_arg_info_is_return_value (GIArgInfo *info)
 {
@ -976,6 +1020,15 @@ g_arg_info_is_return_value (GIArgInfo *info)
  return blob->return_value;
 }

+/**
+ * g_arg_info_is_dipper:
+ * @info: a #GIArgInfo
+ *
+ * Obtain if the argument is a pointer to a struct or object that will
+ * receive an output of a function.
+ *
+ * Returns: %TRUE if it is a dipper argument
+ */
 gboolean
 g_arg_info_is_dipper (GIArgInfo *info)
 {
@ -985,6 +1038,14 @@ g_arg_info_is_dipper (GIArgInfo *info)
  return blob->dipper;
 }

+/**
+ * g_arg_info_is_optional:
+ * @info: a #GIArgInfo
+ *
+ * Obtain if the argument is optional.
+ *
+ * Returns: %TRUE if it is an optional argument
+ */
 gboolean
 g_arg_info_is_optional (GIArgInfo *info)
 {
@ -994,6 +1055,14 @@ g_arg_info_is_optional (GIArgInfo *info)
  return blob->optional;
 }

+/**
+ * g_arg_info_may_be_null:
+ * @info: a #GIArgInfo
+ *
+ * Obtain if the argument accepts %NULL.
+ *
+ * Returns: %TRUE if it accepts %NULL
+ */
 gboolean
 g_arg_info_may_be_null (GIArgInfo *info)
 {
@ -1003,6 +1072,15 @@ g_arg_info_may_be_null (GIArgInfo *info)
  return blob->allow_none;
 }

+/**
+ * g_arg_info_get_ownership_transfer:
+ * @info: a #GIArgInfo
+ *
+ * Obtain the ownership transfer for this argument.
+ * #GITransfer contains a list of possible values.
+ *
+ * Returns: the transfer
+ */
 GITransfer
 g_arg_info_get_ownership_transfer (GIArgInfo *info)
 {
@ -1017,6 +1095,17 @@ g_arg_info_get_ownership_transfer (GIArgInfo *info)
    return GI_TRANSFER_NOTHING;
 }

+/**
+ * g_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.
+ *
+ * Returns: the scope type
+ */
 GIScopeType
 g_arg_info_get_scope (GIArgInfo *info)
 {
@ -1026,6 +1115,15 @@ g_arg_info_get_scope (GIArgInfo *info)
  return blob->scope;
 }

+/**
+ * g_arg_info_get_closure:
+ * @info: a #GIArgInfo
+ *
+ * Obtains 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
+ */
 gint
 g_arg_info_get_closure (GIArgInfo *info)
 {
@ -1035,6 +1133,15 @@ g_arg_info_get_closure (GIArgInfo *info)
  return blob->closure;
 }

+/**
+ * g_arg_info_get_destroy:
+ * @info: a #GIArgInfo
+ *
+ * Obtains the index of the #GDestroyNotify argument. This is only valid
+ * for arguments which are callbacks.
+ *
+ * Returns: index of the #GDestroyNotify argument or -1 if there is none
+ */
 gint
 g_arg_info_get_destroy (GIArgInfo *info)
 {
@ -1048,7 +1155,7 @@ g_arg_info_get_destroy (GIArgInfo *info)
 * g_arg_info_get_type:
 * @info: a #GIArgInfo
 *
- * Obtains the type information for @info.
+ * Obtain the type information for @info.
 *
 * Returns: (transfer full): the #GIArgInfo, free it with
 * g_base_info_unref() when done.
--- a/girepository.h
+++ b/girepository.h
@ -309,9 +309,9 @@ void gi_cclosure_marshal_generic (GClosure       *closure,
 * GIInfoType:
 * @GI_INFO_TYPE_INVALID: invalid type
 * @GI_INFO_TYPE_FUNCTION: function, see #GIFunctionInfo
- * @GI_INFO_TYPE_CALLBACK: callback, see #GICallbackInfo
+ * @GI_INFO_TYPE_CALLBACK: callback, see #GIFunctionInfo
 * @GI_INFO_TYPE_STRUCT: struct, see #GIStructInfo
- * @GI_INFO_TYPE_BOXED: boxed, see #GIBoxedInfo
+ * @GI_INFO_TYPE_BOXED: boxed, see #GIStructInfo or #GIUnionInfo
 * @GI_INFO_TYPE_ENUM: enum, see #GIEnumInfo
 * @GI_INFO_TYPE_FLAGS: flags, see #GIEnumInfo
 * @GI_INFO_TYPE_OBJECT: object, see #GIObjectInfo