gisignalinfo: 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 2023-12-13 13:25:22 +00:00
parent ff30ddb66e
commit 4f5ac0f997
2 changed files with 28 additions and 19 deletions

View File

@ -33,27 +33,30 @@
#include "gisignalinfo.h"
/**
* SECTION:gisignalinfo
* @title: GISignalInfo
* @short_description: Struct representing a signal
* GISignalInfo:
*
* GISignalInfo represents a signal.
* `GISignalInfo` represents a signal.
*
* It's a sub-struct of #GICallableInfo and contains a set of flags and
* a class closure.
* Its a sub-struct of [class@GIRepository.CallableInfo] and contains a set of
* flags and a class closure.
*
* See #GICallableInfo for information on how to retreive arguments
* and other metadata from the signal.
* See [class@GIRepository.CallableInfo] for information on how to retrieve
* arguments and other metadata from the signal.
*
* Since: 2.80
*/
/**
* gi_signal_info_get_flags:
* @info: a #GISignalInfo
*
* Obtain the flags for this signal info. See #GSignalFlags for
* more information about possible flag values.
* Obtain the flags for this signal info.
*
* See [flags@GObject.SignalFlags] for more information about possible flag
* values.
*
* Returns: the flags
* Since: 2.80
*/
GSignalFlags
gi_signal_info_get_flags (GISignalInfo *info)
@ -96,11 +99,14 @@ gi_signal_info_get_flags (GISignalInfo *info)
* gi_signal_info_get_class_closure:
* @info: a #GISignalInfo
*
* Obtain the class closure for this signal if one is set. The class
* closure is a virtual function on the type that the signal belongs to.
* If the signal lacks a closure %NULL will be returned.
* Obtain the class closure for this signal if one is set.
*
* Returns: (transfer full): the class closure or %NULL
* The class closure is a virtual function on the type that the signal belongs
* to. If the signal lacks a closure, `NULL` will be returned.
*
* Returns: (transfer full) (nullable): the class closure, or `NULL` if none is
* set
* Since: 2.80
*/
GIVFuncInfo *
gi_signal_info_get_class_closure (GISignalInfo *info)
@ -123,10 +129,11 @@ gi_signal_info_get_class_closure (GISignalInfo *info)
* gi_signal_info_true_stops_emit:
* @info: a #GISignalInfo
*
* Obtain if the returning true in the signal handler will
* stop the emission of the signal.
* Obtain if the returning `TRUE` in the signal handler will stop the emission
* of the signal.
*
* Returns: %TRUE if returning true stops the signal emission
* Returns: `TRUE` if returning `TRUE` stops the signal emission
* Since: 2.80
*/
gboolean
gi_signal_info_true_stops_emit (GISignalInfo *info)

View File

@ -34,10 +34,12 @@
G_BEGIN_DECLS
/**
* GI_IS_SIGNAL_INFO
* GI_IS_SIGNAL_INFO:
* @info: an info structure
*
* Checks if @info is a #GISignalInfo.
* Checks if @info is a [class@GIRepository.SignalInfo].
*
* Since: 2.80
*/
#define GI_IS_SIGNAL_INFO(info) \
(gi_base_info_get_info_type ((GIBaseInfo*) info) == GI_INFO_TYPE_SIGNAL)