[tepl] SignalGroup: write API docs
- From: Sébastien Wilmet <swilmet src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [tepl] SignalGroup: write API docs
- Date: Mon, 23 Nov 2020 15:50:13 +0000 (UTC)
commit d20ef12a0d98dee034c4f26ff6bf6738e743a131
Author: Sébastien Wilmet <swilmet gnome org>
Date: Mon Nov 23 16:34:13 2020 +0100
SignalGroup: write API docs
docs/reference/tepl-docs.xml | 1 +
docs/reference/tepl-sections.txt | 8 +++++++
tepl/tepl-signal-group.c | 49 +++++++++++++++++++++++++++++++++++++---
3 files changed, 55 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/tepl-docs.xml b/docs/reference/tepl-docs.xml
index 23c9a04..ac0c696 100644
--- a/docs/reference/tepl-docs.xml
+++ b/docs/reference/tepl-docs.xml
@@ -80,6 +80,7 @@
<xi:include href="xml/iter.xml"/>
<xi:include href="xml/panel.xml"/>
<xi:include href="xml/pango.xml"/>
+ <xi:include href="xml/signal-group.xml"/>
<xi:include href="xml/space-drawer-prefs.xml"/>
<xi:include href="xml/statusbar.xml"/>
<xi:include href="xml/style-scheme-chooser-widget.xml"/>
diff --git a/docs/reference/tepl-sections.txt b/docs/reference/tepl-sections.txt
index 5a88add..eb695ef 100644
--- a/docs/reference/tepl-sections.txt
+++ b/docs/reference/tepl-sections.txt
@@ -413,6 +413,14 @@ TeplProgressInfoBarPrivate
tepl_progress_info_bar_get_type
</SECTION>
+<SECTION>
+<FILE>signal-group</FILE>
+TeplSignalGroup
+tepl_signal_group_new
+tepl_signal_group_clear
+tepl_signal_group_add
+</SECTION>
+
<SECTION>
<FILE>space-drawer-prefs</FILE>
TeplSpaceDrawerPrefs
diff --git a/tepl/tepl-signal-group.c b/tepl/tepl-signal-group.c
index 24394ef..a8800dc 100644
--- a/tepl/tepl-signal-group.c
+++ b/tepl/tepl-signal-group.c
@@ -4,10 +4,17 @@
#include "tepl-signal-group.h"
-/* Small utility to disconnect signal handlers without the need to keep around
- * the GObject instance where the signals were connected.
+/**
+ * SECTION:signal-group
+ * @Title: TeplSignalGroup
+ * @Short_description: A group of signal handlers
*
- * It was inspired by DzlSignalGroup from libdazzle. TeplSignalGroup has a much
+ * #TeplSignalGroup is a small utility to disconnect signal handlers without the
+ * need to keep around the #GObject instance that the signal handlers were
+ * connected to.
+ */
+
+/* It was inspired by DzlSignalGroup from libdazzle. TeplSignalGroup has a much
* simpler implementation, it applies the "worse is better" philosophy.
*/
@@ -22,6 +29,17 @@ struct _TeplSignalGroup
GArray *handler_ids;
};
+/**
+ * tepl_signal_group_new: (skip)
+ * @object: a #GObject.
+ *
+ * Creates a new #TeplSignalGroup for @object. The #TeplSignalGroup will have a
+ * weak reference to @object.
+ *
+ * Returns: (transfer full): a new #TeplSignalGroup for @object. Free with
+ * tepl_signal_group_clear() when no longer needed.
+ * Since: 6.0
+ */
TeplSignalGroup *
tepl_signal_group_new (GObject *object)
{
@@ -67,6 +85,20 @@ signal_group_free (TeplSignalGroup *group)
g_free (group);
}
+/**
+ * tepl_signal_group_clear: (skip)
+ * @group_pointer: a pointer to a #TeplSignalGroup.
+ *
+ * Like g_clear_object() but for a #TeplSignalGroup.
+ *
+ * If the #GObject instance of the #TeplSignalGroup is still alive, this
+ * function disconnects all the signal handlers that were added with
+ * tepl_signal_group_add().
+ *
+ * The #TeplSignalGroup, if non-%NULL, is freed when calling this function.
+ *
+ * Since: 6.0
+ */
void
tepl_signal_group_clear (TeplSignalGroup **group_pointer)
{
@@ -76,6 +108,17 @@ tepl_signal_group_clear (TeplSignalGroup **group_pointer)
*group_pointer = NULL;
}
+/**
+ * tepl_signal_group_add: (skip)
+ * @group: a #TeplSignalGroup.
+ * @signal_handler_id: a signal handler ID.
+ *
+ * Adds a signal handler ID to the #TeplSignalGroup. The signal handler must
+ * have been connected to the same #GObject instance as provided to the
+ * tepl_signal_group_new() function when creating @group.
+ *
+ * Since: 6.0
+ */
void
tepl_signal_group_add (TeplSignalGroup *group,
gulong signal_handler_id)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]