diff --git a/gio/gnotification.c b/gio/gnotification.c
index abe68a215..0e48ef077 100644
--- a/gio/gnotification.c
+++ b/gio/gnotification.c
@@ -28,63 +28,53 @@
 #include "gioenumtypes.h"
 
 /**
- * SECTION:gnotification
- * @short_description: User Notifications (pop up messages)
- * @include: gio/gio.h
+ * GNotification:
  *
- * #GNotification is a mechanism for creating a notification to be shown
- * to the user -- typically as a pop-up notification presented by the
+ * `GNotification` is a mechanism for creating a notification to be shown
+ * to the user — typically as a pop-up notification presented by the
  * desktop environment shell.
  *
- * The key difference between #GNotification and other similar APIs is
+ * The key difference between `GNotification` and other similar APIs is
  * that, if supported by the desktop environment, notifications sent
- * with #GNotification will persist after the application has exited,
+ * with `GNotification` will persist after the application has exited,
  * and even across system reboots.
  *
  * Since the user may click on a notification while the application is
- * not running, applications using #GNotification should be able to be
- * started as a D-Bus service, using #GApplication.
+ * not running, applications using `GNotification` should be able to be
+ * started as a D-Bus service, using [class@Gio.Application].
  *
- * In order for #GNotification to work, the application must have installed
+ * In order for `GNotification` to work, the application must have installed
  * a `.desktop` file. For example:
- * |[
- *  [Desktop Entry]
- *   Name=Test Application
- *   Comment=Description of what Test Application does
- *   Exec=gnome-test-application
- *   Icon=org.gnome.TestApplication
- *   Terminal=false
- *   Type=Application
- *   Categories=GNOME;GTK;TestApplication Category;
- *   StartupNotify=true
- *   DBusActivatable=true
- *   X-GNOME-UsesNotifications=true
- * ]|
+ * ```
+ * [Desktop Entry]
+ * Name=Test Application
+ * Comment=Description of what Test Application does
+ * Exec=gnome-test-application
+ * Icon=org.gnome.TestApplication
+ * Terminal=false
+ * Type=Application
+ * Categories=GNOME;GTK;TestApplication Category;
+ * StartupNotify=true
+ * DBusActivatable=true
+ * X-GNOME-UsesNotifications=true
+ * ```
  *
  * The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center
  * that this application uses notifications, so it can be listed in the
  * Control Center’s ‘Notifications’ panel.
  *
  * The `.desktop` file must be named as `org.gnome.TestApplication.desktop`,
- * where `org.gnome.TestApplication` is the ID passed to g_application_new().
+ * where `org.gnome.TestApplication` is the ID passed to
+ * [ctor@Gio.Application.new].
  *
  * User interaction with a notification (either the default action, or
  * buttons) must be associated with actions on the application (ie:
- * "app." actions).  It is not possible to route user interaction
+ * `app.` actions).  It is not possible to route user interaction
  * through the notification itself, because the object will not exist if
  * the application is autostarted as a result of a notification being
  * clicked.
  *
- * A notification can be sent with g_application_send_notification().
- *
- * Since: 2.40
- **/
-
-/**
- * GNotification:
- *
- * This structure type is private and should only be accessed using the
- * public APIs.
+ * A notification can be sent with [method@Gio.Application.send_notification].
  *
  * Since: 2.40
  **/