diff --git a/gobject/gobject.c b/gobject/gobject.c
index 88c8ec108..bfa6e2d24 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -3466,35 +3466,37 @@ g_object_get_property (GObject	   *object,
  * g_object_connect: (skip)
  * @object: (type GObject.Object): a #GObject
  * @signal_spec: the spec for the first signal
- * @...: #GCallback for the first signal, followed by data for the
- *       first signal, followed optionally by more signal
- *       spec/callback/data triples, followed by %NULL
+ * @...: [type@GObject.Callback] for the first signal, followed by data for the
+ *   first signal, followed optionally by more signal
+ *   spec/callback/data triples, followed by `NULL`
  *
  * A convenience function to connect multiple signals at once.
  *
  * The signal specs expected by this function have the form
- * "modifier::signal_name", where modifier can be one of the following:
- * - signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_DEFAULT)
- * - object-signal, object_signal: equivalent to g_signal_connect_object (..., G_CONNECT_DEFAULT)
- * - swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)
- * - swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED)
- * - signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER)
- * - object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER)
- * - swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)
- * - swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)
+ * `modifier::signal_name`, where `modifier` can be one of the
+ * following:
  *
- * |[<!-- language="C" --> 
- *   menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
- * 						   "type", GTK_WINDOW_POPUP,
- * 						   "child", menu,
- * 						   NULL),
- * 				     "signal::event", gtk_menu_window_event, menu,
- * 				     "signal::size_request", gtk_menu_window_size_request, menu,
- * 				     "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
- * 				     NULL);
- * ]|
+ * - `signal`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_DEFAULT)`
+ * - `object-signal`, `object_signal`: equivalent to `g_signal_connect_object (..., G_CONNECT_DEFAULT)`
+ * - `swapped-signal`, `swapped_signal`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)`
+ * - `swapped_object_signal`, `swapped-object-signal`: equivalent to `g_signal_connect_object (..., G_CONNECT_SWAPPED)`
+ * - `signal_after`, `signal-after`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_AFTER)`
+ * - `object_signal_after`, `object-signal-after`: equivalent to `g_signal_connect_object (..., G_CONNECT_AFTER)`
+ * - `swapped_signal_after`, `swapped-signal-after`: equivalent to `g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)`
+ * - `swapped_object_signal_after`, `swapped-object-signal-after`: equivalent to `g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)`
  *
- * Returns: (transfer none) (type GObject.Object): @object
+ * ```c
+ * menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
+ *                                                  "type", GTK_WINDOW_POPUP,
+ *                                                  "child", menu,
+ *                                                  NULL),
+ *                                    "signal::event", gtk_menu_window_event, menu,
+ *                                    "signal::size_request", gtk_menu_window_size_request, menu,
+ *                                    "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
+ *                                    NULL);
+ * ```
+ *
+ * Returns: (transfer none) (type GObject.Object): the object
  */
 gpointer
 g_object_connect (gpointer     _object,