docs: Port to gi-docgen

Fixes: https://gitlab.gnome.org/GNOME/libnotify/-/issues/26

15 files changed, 226 insertions, 161 deletions

diff --git a/docs/reference/libnotify-docs.sgml b/docs/reference/libnotify-docs.sgml
deleted file mode 100644
index f1c8a40..0000000
--- a/docs/reference/libnotify-docs.sgml
+++ /dev/null
@@ -1,30 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>Libnotify Reference Manual</title>
-    <releaseinfo>
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://developer.gnome.org/libnotify/unstable/">http://developer.gnome.org/libnotify/unstable/</ulink>.
-    </releaseinfo>
-  </bookinfo>
-
-  <chapter>
-    <title>Libnotify</title>
-    <xi:include href="xml/notify.xml"/>
-    <xi:include href="xml/notification.xml"/>
-  </chapter>
-
-  <index id="api-index-full">
-    <title id="index-all">Index</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-  </index>
-  <index id="api-index-deprecated" role="deprecated">
-    <title>Index of deprecated symbols</title>
-    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
-  </index>
-
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
-
-</book>
diff --git a/docs/reference/libnotify-overrides.txt b/docs/reference/libnotify-overrides.txt
deleted file mode 100644
index e69de29..0000000
--- a/docs/reference/libnotify-overrides.txt
+++ /dev/null
diff --git a/docs/reference/libnotify-sections.txt b/docs/reference/libnotify-sections.txt
deleted file mode 100644
index f7229c6..0000000
--- a/docs/reference/libnotify-sections.txt
+++ /dev/null
@@ -1,54 +0,0 @@
-<SECTION>
-<FILE>notification</FILE>
-NOTIFY_EXPIRES_DEFAULT
-NOTIFY_EXPIRES_NEVER
-<TITLE>NotifyNotification</TITLE>
-NotifyNotification
-NotifyClosedReason
-NotifyUrgency
-NotifyActionCallback
-NOTIFY_ACTION_CALLBACK
-notify_notification_new
-notify_notification_update
-notify_notification_show
-notify_notification_set_app_name
-notify_notification_set_timeout
-notify_notification_set_category
-notify_notification_set_urgency
-notify_notification_set_icon_from_pixbuf
-notify_notification_set_image_from_pixbuf
-notify_notification_set_hint
-notify_notification_set_hint_int32
-notify_notification_set_hint_uint32
-notify_notification_set_hint_double
-notify_notification_set_hint_string
-notify_notification_set_hint_byte
-notify_notification_set_hint_byte_array
-notify_notification_clear_hints
-notify_notification_add_action
-notify_notification_clear_actions
-notify_notification_close
-notify_notification_get_activation_token
-notify_notification_get_closed_reason
-<SUBSECTION Standard>
-NotifyNotificationPrivate
-NOTIFY_NOTIFICATION
-NOTIFY_IS_NOTIFICATION
-NOTIFY_TYPE_NOTIFICATION
-notify_notification_get_type
-NOTIFY_NOTIFICATION_CLASS
-NOTIFY_IS_NOTIFICATION_CLASS
-NOTIFY_NOTIFICATION_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>notify</FILE>
-notify_init
-notify_uninit
-notify_is_initted
-notify_get_app_name
-notify_set_app_name
-notify_get_server_caps
-notify_get_server_info
-</SECTION>
-
diff --git a/docs/reference/libnotify.toml.in b/docs/reference/libnotify.toml.in
new file mode 100644
index 0000000..debb750
--- /dev/null
+++ b/docs/reference/libnotify.toml.in
@@ -0,0 +1,44 @@
+[library]
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/libnotify/"
+repository_url = "https://gitlab.gnome.org/GNOME/libnotify.git"
+website_url = "https://gitlab.gnome.org/GNOME/libnotify/"
+docs_url = "https://gnome.pages.gitlab.gnome.org/libnotify/"
+authors = "Marco Trevisan, Logan Rathbone, Christian Hammond, Mike Hearn, and John (J5) Palmieri"
+license = "LGPL-2.1-or-later"
+description = ""
+dependencies = [ "GObject-2.0", "GLib-1.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+[dependencies."GObject-2.0"]
+name = "GObject"
+description = "The base type system library"
+docs_url = "https://docs.gtk.org/gobject/"
+
+[dependencies."GLib-2.0"]
+name = "GLib"
+description = "The base type system library"
+docs_url = "https://docs.gtk.org/glib/"
+
+[dependencies."Gio-2.0"]
+name = "GIO"
+description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+docs_url = "https://docs.gtk.org/gio/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/libnotify/-/blob/master"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+]
+
+content_images = [
+]
+urlmap_file = "urlmap.js"
diff --git a/docs/reference/libnotify.types b/docs/reference/libnotify.types
deleted file mode 100644
index 0b54896..0000000
--- a/docs/reference/libnotify.types
+++ /dev/null
@@ -1,3 +0,0 @@
-#include <libnotify/notify.h>
-
-notify_notification_get_type
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 148ff31..df461b1 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,10 +1,40 @@
-gnome.gtkdoc(meson.project_name(),
-  mode: 'sgml',
-  main_sgml: meson.project_name() + '-docs.sgml',
-  src_dir: join_paths(meson.project_source_root(), meson.project_name()),
-  dependencies: libnotify_dep,
-  gobject_typesfile: meson.project_name() + '.types',
-  ignore_headers: ['notify-enum-types.h', 'notify-marshal.h', 'internal.h'],
-  scan_args: [ '--deprecated-guards=LIBNOTIFY_DISABLE_DEPRECATED' ],
+api_version_major = '0'
+expand_content_md_files = []
+
+toml_data = configuration_data()
+toml_data.set('VERSION', meson.project_version())
+
+libnotify_toml = configure_file(
+  input: 'libnotify.toml.in',
+  output: 'libnotify.toml',
+  configuration: toml_data
+)
+
+dependency('gi-docgen', version: '>= 2021.7',
+           fallback: ['gi-docgen', 'dummy_dep'],
+           native: true,
+           required: get_option('gtk_doc'))
+
+gidocgen = find_program('gi-docgen')
+
+docs_dir = get_option('datadir') / 'doc'
+
+custom_target('libnotify-doc',
+  input: [ libnotify_toml, libnotify_gir[0] ],
+  output: 'libnotify-@0@'.format(api_version_major),
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../libnotify'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depend_files: [ expand_content_md_files ],
+  build_by_default: true,
   install: true,
+  install_dir: docs_dir,
 )
diff --git a/docs/reference/urlmap.js b/docs/reference/urlmap.js
new file mode 100644
index 0000000..ffdc69b
--- /dev/null
+++ b/docs/reference/urlmap.js
@@ -0,0 +1,7 @@
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+    ["GdkPixbuf", "https://docs.gtk.org/gdk-pixbuf/"],
+]
diff --git a/libnotify/meson.build b/libnotify/meson.build
index 2258a1d..d4a0b12 100644
--- a/libnotify/meson.build
+++ b/libnotify/meson.build
@@ -72,7 +72,7 @@ introspection = get_option('introspection')
 g_ir_scanner = find_program('g-ir-scanner', required: introspection.enabled())
 
 if g_ir_scanner.found() and not introspection.disabled()
-  gnome.generate_gir(libnotify_lib,
+  libnotify_gir = gnome.generate_gir(libnotify_lib,
     sources: headers + sources + enum_types,
     namespace: 'Notify',
     nsversion: MODULE_VERSION,
diff --git a/libnotify/notification.c b/libnotify/notification.c
index c8c7010..b884ef1 100644
--- a/libnotify/notification.c
+++ b/libnotify/notification.c
@@ -30,9 +30,9 @@
 
 
 /**
- * SECTION:notification
- * @Short_description: A passive pop-up notification.
- * @Title: NotifyNotification
+ * NotifyNotification:
+ *
+ * A passive pop-up notification.
  *
  * #NotifyNotification represents a passive pop-up notification. It can
  * contain summary text, body text, and an icon, as well as hints specifying
@@ -173,6 +173,11 @@ notify_notification_class_init (NotifyNotificationClass *klass)
                               G_TYPE_NONE,
                               0);
 
+        /**
+         * NotifyNotification:id:
+         *
+         * The Id of the notification.
+         */
         g_object_class_install_property (object_class,
                                          PROP_ID,
                                          g_param_spec_int ("id", "ID",
@@ -186,6 +191,13 @@ notify_notification_class_init (NotifyNotificationClass *klass)
                                                            | G_PARAM_STATIC_NICK
                                                            | G_PARAM_STATIC_BLURB));
 
+        /**
+         * NotifyNotification:app-name:
+         *
+         * The name of the application for the notification.
+         *
+         * Since: 0.7.3
+         */
         g_object_class_install_property (object_class,
                                          PROP_APP_NAME,
                                          g_param_spec_string ("app-name",
@@ -197,6 +209,11 @@ notify_notification_class_init (NotifyNotificationClass *klass)
                                                               | G_PARAM_STATIC_NICK
                                                               | G_PARAM_STATIC_BLURB));
 
+        /**
+         * NotifyNotification:summary:
+         *
+         * The summary of the notification.
+         */
         g_object_class_install_property (object_class,
                                          PROP_SUMMARY,
                                          g_param_spec_string ("summary",
@@ -209,6 +226,11 @@ notify_notification_class_init (NotifyNotificationClass *klass)
                                                               | G_PARAM_STATIC_NICK
                                                               | G_PARAM_STATIC_BLURB));
 
+        /**
+         * NotifyNotification:body:
+         *
+         * The body of the notification.
+         */
         g_object_class_install_property (object_class,
                                          PROP_BODY,
                                          g_param_spec_string ("body",
@@ -221,6 +243,11 @@ notify_notification_class_init (NotifyNotificationClass *klass)
                                                               | G_PARAM_STATIC_NICK
                                                               | G_PARAM_STATIC_BLURB));
 
+        /**
+         * NotifyNotification:icon-name:
+         *
+         * The icon-name of the icon to be displayed on the notification.
+         */
         g_object_class_install_property (object_class,
                                          PROP_ICON_NAME,
                                          g_param_spec_string ("icon-name",
@@ -233,6 +260,13 @@ notify_notification_class_init (NotifyNotificationClass *klass)
                                                               | G_PARAM_STATIC_NICK
                                                               | G_PARAM_STATIC_BLURB));
 
+        /**
+         * NotifyNotification:closed-reason:
+         *
+         * The closed reason of the notification.
+         *
+         * See [signal@Notification::closed].
+         */
         g_object_class_install_property (object_class,
                                          PROP_CLOSED_REASON,
                                          g_param_spec_int ("closed-reason",
@@ -443,8 +477,9 @@ maybe_warn_portal_unsupported_feature (const char *feature_name)
  * @body: (allow-none): The optional body text.
  * @icon: (allow-none): The optional icon theme icon name or filename.
  *
- * Creates a new #NotifyNotification. The summary text is required, but
- * all other parameters are optional.
+ * Creates a new #NotifyNotification.
+ *
+ * The summary text is required, but all other parameters are optional.
  *
  * Returns: The new #NotifyNotification.
  */
@@ -601,9 +636,10 @@ notify_notification_update_internal (NotifyNotification *notification,
  * @body: (allow-none): The optional body text.
  * @icon: (allow-none): The optional icon theme icon name or filename.
  *
- * Updates the notification text and icon. This won't send the update out
- * and display it on the screen. For that, you will need to call
- * notify_notification_show().
+ * Updates the notification text and icon.
+ *
+ * This won't send the update out and display it on the screen. For that, you
+ * will need to call [method@Notification.show].
  *
  * Returns: %TRUE, unless an invalid parameter was passed.
  */
@@ -1055,7 +1091,7 @@ add_portal_notification (GDBusProxy         *proxy,
  * Tells the notification server to display the notification on the screen.
  *
  * Returns: %TRUE if successful. On error, this will return %FALSE and set
- *          @error.
+ *   @error.
  */
 gboolean
 notify_notification_show (NotifyNotification *notification,
@@ -1179,9 +1215,10 @@ notify_notification_show (NotifyNotification *notification,
  * @notification: The notification.
  * @timeout: The timeout in milliseconds.
  *
- * Sets the timeout of the notification. To set the default time, pass
- * %NOTIFY_EXPIRES_DEFAULT as @timeout. To set the notification to never
- * expire, pass %NOTIFY_EXPIRES_NEVER.
+ * Sets the timeout of the notification.
+ *
+ * To set the default time, pass %NOTIFY_EXPIRES_DEFAULT as @timeout. To set the
+ * notification to never expire, pass %NOTIFY_EXPIRES_NEVER.
  *
  * Note that the timeout may be ignored by the server.
  */
@@ -1209,8 +1246,10 @@ _notify_notification_get_timeout (const NotifyNotification *notification)
  * @notification: The notification.
  * @category: The category.
  *
- * Sets the category of this notification. This can be used by the
- * notification server to filter or display the data in a certain way.
+ * Sets the category of this notification.
+ *
+ * This can be used by the notification server to filter or display the data in
+ * a certain way.
  */
 void
 notify_notification_set_category (NotifyNotification *notification,
@@ -1236,8 +1275,6 @@ notify_notification_set_category (NotifyNotification *notification,
  * @urgency: The urgency level.
  *
  * Sets the urgency level of this notification.
- *
- * See: #NotifyUrgency
  */
 void
 notify_notification_set_urgency (NotifyNotification *notification,
@@ -1257,8 +1294,8 @@ notify_notification_set_urgency (NotifyNotification *notification,
  * @icon: The icon.
  *
  * Sets the icon in the notification from a #GdkPixbuf.
- * Deprecated: use notify_notification_set_image_from_pixbuf() instead.
  *
+ * Deprecated: use [method@Notification.set_image_from_pixbuf] instead.
  */
 void
 notify_notification_set_icon_from_pixbuf (NotifyNotification *notification,
@@ -1272,8 +1309,7 @@ notify_notification_set_icon_from_pixbuf (NotifyNotification *notification,
  * @notification: The notification.
  * @pixbuf: The image.
  *
- * Sets the image in the notification from a #GdkPixbuf.
- *
+ * Sets the image in the notification from a [class@GdkPixbuf.Pixbuf].
  */
 void
 notify_notification_set_image_from_pixbuf (NotifyNotification *notification,
@@ -1392,8 +1428,9 @@ maybe_parse_snap_hint_value (NotifyNotification *notification,
  * @key: the hint key
  * @value: (allow-none): the hint value, or %NULL to unset the hint
  *
- * Sets a hint for @key with value @value. If @value is %NULL,
- * a previously set hint for @key is unset.
+ * Sets a hint for @key with value @value.
+ *
+ * If @value is %NULL, a previously set hint for @key is unset.
  *
  * If @value is floating, it is consumed.
  *
@@ -1422,10 +1459,11 @@ notify_notification_set_hint (NotifyNotification *notification,
  * @notification: a #NotifyNotification
  * @app_name: the localised application name
  *
- * Sets the application name for the notification. If this function is
- * not called or if @app_name is %NULL, the application name will be
- * set from the value used in notify_init() or overridden with
- * notify_set_app_name().
+ * Sets the application name for the notification.
+ *
+ * If this function is not called or if @app_name is %NULL, the application name
+ * will be set from the value used in [func@init] or overridden with
+ * [func@set_app_name].
  *
  * Since: 0.7.3
  */
@@ -1453,7 +1491,7 @@ notify_notification_set_app_name (NotifyNotification *notification,
  *
  * Sets a hint with a 32-bit integer value.
  *
- * Deprecated: 0.6. Use notify_notification_set_hint() instead
+ * Deprecated: 0.6. Use [method@Notification.set_hint] instead
  */
 void
 notify_notification_set_hint_int32 (NotifyNotification *notification,
@@ -1473,7 +1511,7 @@ notify_notification_set_hint_int32 (NotifyNotification *notification,
  *
  * Sets a hint with an unsigned 32-bit integer value.
  *
- * Deprecated: 0.6. Use notify_notification_set_hint() instead
+ * Deprecated: 0.6. Use [method@Notification.set_hint] instead
  */
 void
 notify_notification_set_hint_uint32 (NotifyNotification *notification,
@@ -1492,7 +1530,7 @@ notify_notification_set_hint_uint32 (NotifyNotification *notification,
  *
  * Sets a hint with a double value.
  *
- * Deprecated: 0.6. Use notify_notification_set_hint() instead
+ * Deprecated: 0.6. Use [method@Notification.set_hint] instead
  */
 void
 notify_notification_set_hint_double (NotifyNotification *notification,
@@ -1511,7 +1549,7 @@ notify_notification_set_hint_double (NotifyNotification *notification,
  *
  * Sets a hint with a byte value.
  *
- * Deprecated: 0.6. Use notify_notification_set_hint() instead
+ * Deprecated: 0.6. Use [method@Notification.set_hint] instead
  */
 void
 notify_notification_set_hint_byte (NotifyNotification *notification,
@@ -1529,10 +1567,11 @@ notify_notification_set_hint_byte (NotifyNotification *notification,
  * @value: (array length=len): The hint's value.
  * @len: The length of the byte array.
  *
- * Sets a hint with a byte array value. The length of @value must be passed
- * as @len.
+ * Sets a hint with a byte array value.
+ *
+ * The length of @value must be passed as @len.
  *
- * Deprecated: 0.6. Use notify_notification_set_hint() instead
+ * Deprecated: 0.6. Use [method@Notification.set_hint] instead
  */
 void
 notify_notification_set_hint_byte_array (NotifyNotification *notification,
@@ -1566,7 +1605,7 @@ notify_notification_set_hint_byte_array (NotifyNotification *notification,
  *
  * Sets a hint with a string value.
  *
- * Deprecated: 0.6. Use notify_notification_set_hint() instead
+ * Deprecated: 0.6. Use [method@Notification.set_hint] instead
  */
 void
 notify_notification_set_hint_string (NotifyNotification *notification,
@@ -1638,11 +1677,12 @@ notify_notification_clear_actions (NotifyNotification *notification)
  * @callback: The action's callback function.
  * @user_data: Optional custom data to pass to @callback.
  * @free_func: (type GLib.DestroyNotify): An optional function to free @user_data when the notification
- *             is destroyed.
+ *   is destroyed.
  *
- * Adds an action to a notification. When the action is invoked, the
- * specified callback function will be called, along with the value passed
- * to @user_data.
+ * Adds an action to a notification.
+ *
+ * When the action is invoked, the specified callback function will be called,
+ * along with the value passed to @user_data.
  */
 void
 notify_notification_add_action (NotifyNotification  *notification,
@@ -1681,8 +1721,10 @@ notify_notification_add_action (NotifyNotification  *notification,
  * notify_notification_get_activation_token:
  * @notification: The notification.
  *
+ * Gets the activation token of the notification.
+ *
  * If an an action is currently being activated, return the activation token.
- * This function is intended to be used in a #NotifyActionCallback to get
+ * This function is intended to be used in a [callback@ActionCallback] to get
  * the activation token for the activated action, if the notification daemon
  * supports it.
  *
@@ -1762,13 +1804,14 @@ notify_notification_close (NotifyNotification *notification,
  * notify_notification_get_closed_reason:
  * @notification: The notification.
  *
- * Returns the closed reason code for the notification. This is valid only
- * after the "closed" signal is emitted.
+ * Returns the closed reason code for the notification.
+ *
+ * This is valid only after the [signal@Notification::closed] signal is emitted.
  *
- * Since version 0.8.0 the returned value is of type #NotifyClosedReason.
+ * Since version 0.8.0 the returned value is of type [enum@ClosedReason].
  *
  * Returns: An integer representing the closed reason code
- *  (Since 0.8.0 it's also a #NotifyClosedReason).
+ *   (Since 0.8.0 it's also a [enum@ClosedReason]).
  */
 gint
 notify_notification_get_closed_reason (const NotifyNotification *notification)
diff --git a/libnotify/notification.h b/libnotify/notification.h
index f0c8e69..6e2ea4d 100644
--- a/libnotify/notification.h
+++ b/libnotify/notification.h
@@ -39,8 +39,9 @@ G_BEGIN_DECLS
 /**
  * NOTIFY_EXPIRES_NEVER:
  *
- * The notification never expires. It stays open until closed by the calling API
- * or the user.
+ * The notification never expires.
+ *
+ * It stays open until closed by the calling API or the user.
  */
 #define NOTIFY_EXPIRES_NEVER    0
 
@@ -100,7 +101,7 @@ typedef enum
  * @NOTIFY_CLOSED_REASON_EXPIRED: Timeout has expired.
  * @NOTIFY_CLOSED_REASON_DISMISSED: It has been dismissed by the user.
  * @NOTIFY_CLOSED_REASON_API_REQUEST: It has been closed by a call to
- *   notify_notification_close().
+ *   [method@Notify.close].
  * @NOTIFY_CLOSED_REASON_UNDEFIEND: Closed by undefined/reserved reasons.
  *
  * The reason for which the notification has been closed.
@@ -132,8 +133,9 @@ typedef void    (*NotifyActionCallback) (NotifyNotification *notification,
  * NOTIFY_ACTION_CALLBACK:
  * @func: The function to cast.
  *
- * A convenience macro for casting a function to a #NotifyActionCallback. This
- * is much like G_CALLBACK().
+ * A convenience macro for casting a function to a [callback@ActionCallback].
+ *
+ * This is much like [func@GObject.CALLBACK].
  */
 #define NOTIFY_ACTION_CALLBACK(func) ((NotifyActionCallback)(func))
 
diff --git a/libnotify/notify-features.h.in b/libnotify/notify-features.h.in
index 265bdcc..b03f4c6 100644
--- a/libnotify/notify-features.h.in
+++ b/libnotify/notify-features.h.in
@@ -23,12 +23,34 @@
 
 /* compile time version
  */
+
+/**
+ * NOTIFY_VERSION_MAJOR:
+ *
+ * Adwaita major version component (e.g. 1 if the version is 1.2.3).
+ */
 #define NOTIFY_VERSION_MAJOR    (@LIBNOTIFY_MAJOR_VERSION@)
+/**
+ * NOTIFY_VERSION_MINOR:
+ *
+ * Adwaita minor version component (e.g. 2 if the version is 1.2.3).
+ */
 #define NOTIFY_VERSION_MINOR    (@LIBNOTIFY_MINOR_VERSION@)
+/**
+ * NOTIFY_VERSION_MICRO:
+ *
+ * Adwaita micro version component (e.g. 3 if the version is 1.2.3).
+ */
 #define NOTIFY_VERSION_MICRO    (@LIBNOTIFY_MICRO_VERSION@)
 
-/* check whether a version equal to or greater than
- * major.minor.micro is present.
+/**
+ * NOTIFY_CHECK_VERSION:
+ * @major: required major version
+ * @minor: required minor version
+ * @micro: required micro version
+ *
+ * check whether a version equal to or greater than
+ * `major.minor.micro` is present.
  */
 #define NOTIFY_CHECK_VERSION(major,minor,micro) \
     (NOTIFY_VERSION_MAJOR > (major) || \
diff --git a/libnotify/notify.c b/libnotify/notify.c
index 362ba3d..ee98ba2 100644
--- a/libnotify/notify.c
+++ b/libnotify/notify.c
@@ -35,12 +35,6 @@
 #include "internal.h"
 #include "notify-marshal.h"
 
-/**
- * SECTION:notify
- * @Short_description: Notification API
- * @Title: notify
- */
-
 static gboolean         _initted = FALSE;
 static char            *_app_name = NULL;
 static char            *_snap_name = NULL;
@@ -432,7 +426,7 @@ _notify_uses_portal_notifications (void)
  *
  * Gets the application name registered.
  *
- * Returns: The registered application name, passed to notify_init().
+ * Returns: The registered application name, passed to [func@init].
  */
 const char *
 notify_get_app_name (void)
@@ -443,7 +437,7 @@ notify_get_app_name (void)
 /**
  * notify_uninit:
  *
- * Uninitialized libnotify.
+ * Uninitializes libnotify.
  *
  * This should be called when the program no longer needs libnotify for
  * the rest of its lifecycle, typically just before exitting.
@@ -592,10 +586,12 @@ out:
 /**
  * notify_get_server_caps:
  *
- * Synchronously queries the server for its capabilities and returns them in a #GList.
+ * Queries the server capabilities.
  *
- * Returns: (transfer full) (element-type utf8): a #GList of server capability strings. Free
- *   the list elements with g_free() and the list itself with g_list_free().
+ * Synchronously queries the server for its capabilities and returns them in a
+ * list.
+ *
+ * Returns: (transfer full) (element-type utf8): a list of server capability strings.
  */
 GList *
 notify_get_server_caps (void)
@@ -654,12 +650,14 @@ notify_get_server_caps (void)
  * @ret_version: (out) (allow-none) (transfer full): a location to store the server version, or %NULL
  * @ret_spec_version: (out) (allow-none) (transfer full): a location to store the version the service is compliant with, or %NULL
  *
- * Synchronously queries the server for its information, specifically, the name, vendor,
- * server version, and the version of the notifications specification that it
- * is compliant with.
+ * Queries the server for information.
+ *
+ * Synchronously queries the server for its information, specifically, the name,
+ * vendor, server version, and the version of the notifications specification
+ * that it is compliant with.
  *
  * Returns: %TRUE if successful, and the variables passed will be set, %FALSE
- *          on error. The returned strings must be freed with g_free
+ *   on error. The returned strings must be freed with g_free
  */
 gboolean
 notify_get_server_info (char **ret_name,
diff --git a/meson_options.txt b/meson_options.txt
index c57b364..d20d16d 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -13,7 +13,7 @@ option('man',
 option('gtk_doc',
   type: 'boolean',
   value: true,
-  description: 'Enable generating the API reference (depends on GTK-Doc)')
+  description: 'Enable generating the API reference (depends on gi-docgen)')
 option('docbook_docs',
   type: 'feature',
   value: 'auto',
diff --git a/subprojects/gi-docgen b/subprojects/gi-docgen
new file mode 160000
+Subproject 5ced0db97c1d38de83637d4e80749f35a1791bf
diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap
new file mode 100644
index 0000000..98cd921
--- /dev/null
+++ b/subprojects/gi-docgen.wrap
@@ -0,0 +1,6 @@
+[wrap-git]
+directory=gi-docgen
+url=https://gitlab.gnome.org/GNOME/gi-docgen.git
+push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git
+revision=main
+depth=1