[libpeas] gi-docgen: Port individual docstrings



commit b068425289275e88c964089e782066a7e29c8632
Author: Maximiliano Sandoval R <msandova gnome org>
Date:   Sun Mar 13 12:26:29 2022 +0100

    gi-docgen: Port individual docstrings

 libpeas-gtk/peas-gtk-configurable.c        |  21 ++--
 libpeas-gtk/peas-gtk-plugin-manager-view.c |  16 +--
 libpeas-gtk/peas-gtk-plugin-manager.c      |  19 ++--
 libpeas/peas-activatable.c                 |  16 +--
 libpeas/peas-engine.c                      | 176 +++++++++++++++--------------
 libpeas/peas-extension-base.c              |  20 ++--
 libpeas/peas-extension-set.c               |  90 ++++++++-------
 libpeas/peas-extension-set.h               |   2 +-
 libpeas/peas-extension.c                   |  33 +++---
 libpeas/peas-object-module.c               |  61 +++++-----
 libpeas/peas-object-module.h               |   6 +-
 libpeas/peas-plugin-info.c                 |  45 ++++----
 libpeas/peas-version.h.in                  |   9 +-
 13 files changed, 266 insertions(+), 248 deletions(-)
---
diff --git a/libpeas-gtk/peas-gtk-configurable.c b/libpeas-gtk/peas-gtk-configurable.c
index 3e9ea67e..afd634cb 100644
--- a/libpeas-gtk/peas-gtk-configurable.c
+++ b/libpeas-gtk/peas-gtk-configurable.c
@@ -26,18 +26,19 @@
 #include "peas-gtk-configurable.h"
 
 /**
- * SECTION:peas-gtk-configurable
- * @short_description: Interface for providing a plugin configuration UI.
+ * PeasGtkConfigurable:
+ *
+ * Interface for providing a plugin configuration UI.
  *
  * The #PeasGtkConfigurable interface will allow a plugin to provide a
  * graphical interface for the user to configure the plugin through the
- * #PeasGtkPluginManager: the #PeasGtkPluginManager will make its
+ * [class@PluginManager]: the #PeasGtkPluginManager will make its
  * “Configure Plugin” button active when the selected plugin implements
  * the #PeasGtkConfigurable interface.
  *
  * To allow plugin configuration from the #PeasGtkPluginManager, the
  * plugin writer will just need to implement the
- * PeasGtkConfigurableInterface.create_configure_widget() method.
+ * [method@Configurable.create_configure_widget] method.
  **/
 
 G_DEFINE_INTERFACE(PeasGtkConfigurable, peas_gtk_configurable, G_TYPE_OBJECT)
@@ -51,15 +52,17 @@ peas_gtk_configurable_default_init (PeasGtkConfigurableInterface *iface)
  * peas_gtk_configurable_create_configure_widget:
  * @configurable: A #PeasGtkConfigurable
  *
- * Creates the configure widget for the plugin. The returned widget
- * should allow configuring all the relevant aspects of the plugin, and should
- * allow instant-apply, as promoted by the Gnome Human Interface Guidelines.
+ * Creates the configure widget for the plugin.
+ *
+ * The returned widget should allow configuring all the relevant aspects of the
+ * plugin, and should allow instant-apply, as promoted by the Gnome Human
+ * Interface Guidelines.
  *
- * #PeasGtkPluginManager will embed the returned widget into a dialog box,
+ * [class@PluginManager] will embed the returned widget into a dialog box,
  * but you shouldn't take this behaviour for granted as other implementations
  * of a plugin manager UI might do otherwise.
  *
- * This method should always return a valid #GtkWidget instance, never %NULL.
+ * This method should always return a valid [class@Gtk.Widget] instance, never %NULL.
  *
  * Returns: (transfer full): A #GtkWidget used for configuration.
  */
diff --git a/libpeas-gtk/peas-gtk-plugin-manager-view.c b/libpeas-gtk/peas-gtk-plugin-manager-view.c
index 462e44e2..73c1a8db 100644
--- a/libpeas-gtk/peas-gtk-plugin-manager-view.c
+++ b/libpeas-gtk/peas-gtk-plugin-manager-view.c
@@ -37,15 +37,16 @@
 #include "peas-gtk-configurable.h"
 
 /**
- * SECTION:peas-gtk-plugin-manager-view
- * @short_description: Management tree view for plugins.
+ * PeasGtkPluginManagerView:
+ *
+ * Management tree view for plugins.
  *
  * The #PeasGtkPluginManagerView is a tree view that can be used to manage
  * plugins, i.e. load or unload them, and see some pieces of information.
  *
  * The only thing you need to do as an application writer if you wish
  * to use the view to display your plugins is to instantiate it using
- * peas_gtk_plugin_manager_view_new() and pack it into another
+ * [ctor PluginManagerView new] and pack it into another
  * widget or a window.
  *
  * Note: Changing the model of the view is not supported.
@@ -833,7 +834,7 @@ peas_gtk_plugin_manager_view_class_init (PeasGtkPluginManagerViewClass *klass)
   /**
    * PeasGtkPLuginManagerView:engine:
    *
-   * The #PeasEngine this view is attached to.
+   * The [class@Peas.Engine] this view is attached to.
    */
   properties[PROP_ENGINE] =
     g_param_spec_object ("engine",
@@ -865,8 +866,9 @@ peas_gtk_plugin_manager_view_class_init (PeasGtkPluginManagerViewClass *klass)
    * @view: A #PeasGtkPluginManagerView.
    * @menu: A #GtkMenu.
    *
-   * The ::populate-popup signal is emitted before showing the context
-   * menu of the view. If you need to add items to the context menu,
+   * Emitted before showing the context menu of the view.
+   *
+   * If you need to add items to the context menu,
    * connect to this signal and add your menuitems to the @menu.
    */
   signals[POPULATE_POPUP] =
@@ -887,7 +889,7 @@ peas_gtk_plugin_manager_view_class_init (PeasGtkPluginManagerViewClass *klass)
  * peas_gtk_plugin_manager_view_new:
  * @engine: (allow-none): A #PeasEngine, or %NULL.
  *
- * Creates a new plugin manager view for the given #PeasEngine.
+ * Creates a new plugin manager view for the given [class@Peas.Engine].
  *
  * If @engine is %NULL, then the default engine will be used.
  *
diff --git a/libpeas-gtk/peas-gtk-plugin-manager.c b/libpeas-gtk/peas-gtk-plugin-manager.c
index 88b82758..9d7d8127 100644
--- a/libpeas-gtk/peas-gtk-plugin-manager.c
+++ b/libpeas-gtk/peas-gtk-plugin-manager.c
@@ -42,17 +42,20 @@
 #include "peas-gtk-configurable.h"
 
 /**
- * SECTION:peas-gtk-plugin-manager
- * @short_description: Management GUI for plugins.
+ * PeasGtkPluginManager:
+ *
+ * Management GUI for plugins.
  *
  * The #PeasGtkPluginManager is a widget that can be used to manage plugins,
  * i.e. load or unload them, and see some pieces of information.
  *
- * <inlinegraphic fileref="peas-gtk-plugin-manager.png" format="PNG" />
+ * <picture>
+ *   <source srcset="peas-gtk-plugin-manager.png">
+ * </picture>
  *
  * The only thing you need to do as an application writer if you wish to use
  * the manager to configure your plugins is to instantiate it using
- * peas_gtk_plugin_manager_new() and pack it into another widget or a window
+ * [ctor PluginManager new] and pack it into another widget or a window
  * (as in the screenshot above).
  *
  **/
@@ -547,7 +550,7 @@ peas_gtk_plugin_manager_class_init (PeasGtkPluginManagerClass *klass)
   /**
    * PeasGtkPluginManager:engine:
    *
-   * The #PeasEngine this manager is attached to.
+   * The [class@Peas.Engine] this manager is attached to.
    */
   properties[PROP_ENGINE] =
     g_param_spec_object ("engine",
@@ -561,7 +564,7 @@ peas_gtk_plugin_manager_class_init (PeasGtkPluginManagerClass *klass)
   /**
    * PeasGtkPluginManager:view:
    *
-   * The #PeasGtkPluginManagerView shown in the #PeasGtkPluginManager.
+   * The [class@PluginManagerView] shown in the #PeasGtkPluginManager.
    */
   properties[PROP_VIEW] =
     g_param_spec_object ("view",
@@ -579,7 +582,7 @@ peas_gtk_plugin_manager_class_init (PeasGtkPluginManagerClass *klass)
  * peas_gtk_plugin_manager_new:
  * @engine: (allow-none): A #PeasEngine, or %NULL.
  *
- * Creates a new plugin manager for the given #PeasEngine.
+ * Creates a new plugin manager for the given [class@Peas.Engine].
  *
  * If @engine is %NULL, then the default engine will be used.
  *
@@ -599,7 +602,7 @@ peas_gtk_plugin_manager_new (PeasEngine *engine)
  * peas_gtk_plugin_manager_get_view:
  * @pm: A #PeasGtkPluginManager.
  *
- * Returns the #PeasGtkPluginManagerView of @pm.
+ * Returns the [class@PluginManagerView] of @pm.
  *
  * Returns: (transfer none): the #GtkTreeView of @pm.
  */
diff --git a/libpeas/peas-activatable.c b/libpeas/peas-activatable.c
index acdcc2f3..7714d1de 100644
--- a/libpeas/peas-activatable.c
+++ b/libpeas/peas-activatable.c
@@ -24,9 +24,9 @@
 #include "peas-activatable.h"
 
 /**
- * SECTION:peas-activatable
- * @short_description: Interface for activatable plugins.
- * @see_also: #PeasExtensionSet
+ * PeasActivatable:
+ *
+ * Interface for activatable plugins.
  *
  * #PeasActivatable is an interface which should be implemented by plugins
  * that should be activated on an object of a certain type (depending on the
@@ -34,7 +34,7 @@
  * #PeasActivatable plugin instances could be bound to individual toplevel
  * windows.
  *
- * It is typical to use #PeasActivatable along with #PeasExtensionSet in order
+ * It is typical to use #PeasActivatable along with [class@ExtensionSet] in order
  * to activate and deactivate extensions automatically when plugins are loaded
  * or unloaded.
  *
@@ -51,9 +51,11 @@ peas_activatable_default_init (PeasActivatableInterface *iface)
   /**
    * PeasActivatable:object:
    *
-   * The object property contains the targetted object for this
-   * #PeasActivatable instance, for example a toplevel window in a typical
-   * windowed application. It is set at construction time and won't change.
+   * The object property contains the targetted object for this #PeasActivatable
+   * instance.
+   *
+   * For example a toplevel window in a typical windowed application. It is set
+   * at construction time and won't change.
    */
   g_object_interface_install_property (iface,
                                        g_param_spec_object ("object",
diff --git a/libpeas/peas-engine.c b/libpeas/peas-engine.c
index b3f48576..9929f69f 100644
--- a/libpeas/peas-engine.c
+++ b/libpeas/peas-engine.c
@@ -38,26 +38,19 @@
 #include "peas-utils.h"
 
 /**
- * SECTION:peas-engine
- * @short_description: Engine at the heart of the Peas plugin system.
- * @see_also: #PeasPluginInfo
+ * PeasEngine:
  *
  * The #PeasEngine is the object which manages the plugins.
  *
  * Its role is twofold:
- * <itemizedlist>
- *   <listitem>
- *     <para>it will fetch all the information about the available plugins
- *     from all the registered plugin directories;</para>
- *   </listitem>
- *   <listitem>
- *     <para>it will provide you an API to load, control and unload your
- *     plugins and their extensions from within your application.</para>
- *   </listitem>
- * </itemizedlist>
- *
- * Since libpeas 1.22, @extension_type can be an Abstract #GType
- * and not just an Interface #GType.
+ *
+ * - it will fetch all the information about the available plugins
+ *   from all the registered plugin directories;
+ * - it will provide you an API to load, control and unload your
+ *   plugins and their extensions from within your application.
+ *
+ * Since libpeas 1.22, @extension_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  **/
 
 /* Signals */
@@ -413,8 +406,7 @@ peas_engine_insert_search_path (PeasEngine  *engine,
  * @module_dir: the plugin module directory.
  * @data_dir: (allow-none): the plugin data directory.
  *
- * This function appends a search path to the list of paths where to
- * look for plugins.
+ * Appends a search path to the list of paths where to look for plugins.
  *
  * A so-called "search path" actually consists of both a
  * module directory (where the shared libraries or language modules
@@ -425,7 +417,7 @@ peas_engine_insert_search_path (PeasEngine  *engine,
  * when it comes to installation location: the same plugin can be
  * installed either in the system path or in the user's home directory,
  * without taking other special care than using
- * peas_plugin_info_get_data_dir() when looking for its data files.
+ * [method@PluginInfo.get_data_dir] when looking for its data files.
  *
  * If @data_dir is %NULL, then it is set to the same value as
  * @module_dir.
@@ -444,10 +436,9 @@ peas_engine_add_search_path (PeasEngine  *engine,
  * @module_dir: the plugin module directory.
  * @data_dir: (allow-none): the plugin data directory.
  *
- * This function prepends a search path to the list of paths where to
- * look for plugins.
+ * Prepends a search path to the list of paths where to look for plugins.
  *
- * See Also: peas_engine_add_search_path()
+ * See Also: [method@Engine.add_search_path]
  *
  * Since: 1.6
  */
@@ -509,8 +500,10 @@ peas_engine_init (PeasEngine *engine)
  * peas_engine_garbage_collect:
  * @engine: A #PeasEngine.
  *
- * This function triggers garbage collection on all the loaders currently
- * owned by the #PeasEngine.  This can be used to force the loaders to destroy
+ * Triggers garbage collection on all the loaders currently owned by the
+ * #PeasEngine.
+ *
+ * This can be used to force the loaders to destroy
  * managed objects that still hold references to objects that are about to
  * disappear.
  */
@@ -664,7 +657,7 @@ peas_engine_class_init (PeasEngineClass *klass)
    *
    * The list of found plugins.
    *
-   * This will be modified when peas_engine_rescan_plugins() is called.
+   * This will be modified when [method@Engine.rescan_plugins] is called.
    *
    * Note: the list belongs to the engine and should not be modified or freed.
    */
@@ -680,18 +673,19 @@ peas_engine_class_init (PeasEngineClass *klass)
    *
    * The list of loaded plugins.
    *
-   * This will be modified when peas_engine_load_plugin() or
-   * peas_engine_unload_plugin() is called.
+   * This will be modified when [method@Engine.load_plugin] or
+   * [method@Engine.unload_plugin] is called.
    *
-   * This can be used with GSettings to save the loaded plugins by binding
-   * to this property after instantiating the engine by doing:
-   * |[
+   * This can be used with [class@Gio.Settings] to save the loaded plugins by
+   * binding to this property after instantiating the engine by doing:
+   *
+   * ```c
    *   g_settings_bind (gsettings_object,
    *                    LOADED_PLUGINS_KEY,
    *                    engine,
    *                    "loaded-plugins",
    *                    G_SETTINGS_BIND_DEFAULT);
-   * ]|
+   * ```
    *
    * Note: notify will not be called when the engine is being destroyed.
    */
@@ -708,7 +702,7 @@ peas_engine_class_init (PeasEngineClass *klass)
    *
    * If non-global plugin loaders should be used.
    *
-   * See peas_engine_new_with_nonglobal_loaders() for more information.
+   * See [ctor@Engine.new_with_nonglobal_loaders] for more information.
    *
    * Since: 1.14
    */
@@ -730,9 +724,9 @@ peas_engine_class_init (PeasEngineClass *klass)
    *
    * The plugin is being loaded in the default handler. Hence, if you want to
    * perform some action before the plugin is loaded, you should use
-   * g_signal_connect(), but if you want to perform some action *after* the
+   * [func@GObject.signal_connect], but if you want to perform some action *after* the
    * plugin is loaded (the most common case), you should use
-   * g_signal_connect_after().
+   * [func@GObject.signal_connect_after].
    */
   signals[LOAD_PLUGIN] =
     g_signal_new (I_("load-plugin"),
@@ -753,11 +747,11 @@ peas_engine_class_init (PeasEngineClass *klass)
    *
    * The unload-plugin signal is emitted when a plugin is being unloaded.
    *
-   * The plugin is being unloaded in the default handler. Hence, if you want
-   * to perform some action before the plugin is unloaded (the most common
-   * case), you should use g_signal_connect(), but if you want to perform some
-   * action after the plugin is unloaded (the most common case), you should
-   * use g_signal_connect_after().
+   * The plugin is being unloaded in the default handler. Hence, if you want to
+   * perform some action before the plugin is unloaded (the most common case),
+   * you should use [func@GObject.signal_connect], but if you want to perform
+   * some action after the plugin is unloaded (the most common case), you should
+   * use [func@GObject.signal_connect_after].
    */
   signals[UNLOAD_PLUGIN] =
     g_signal_new (I_("unload-plugin"),
@@ -945,19 +939,21 @@ get_plugin_loader (PeasEngine *engine,
  * @loader_name: The name of the loader to enable.
  *
  * Enable a loader, enables a loader for plugins.
+ *
  * The C plugin loader is always enabled. The other plugin
  * loaders are: lua5.1, python and python3.
  *
  * For instance, the following code will enable Python 2 plugins
  * to be loaded:
- * |[
+ *
+ * ```c
  * peas_engine_enable_loader (engine, "python");
- * ]|
+ * ```
  *
- * Note: plugin loaders used to be shared across #PeasEngines so enabling
- *       a loader on one #PeasEngine would enable it on all #PeasEngines.
- *       This behavior has been kept to avoid breaking applications,
- *       however a warning has been added to help applications transition.
+ * Note: plugin loaders used to be shared across `PeasEngine`s so enabling
+ *   a loader on one #PeasEngine would enable it on all #PeasEngines.
+ *   This behavior has been kept to avoid breaking applications,
+ *   however a warning has been added to help applications transition.
  **/
 void
 peas_engine_enable_loader (PeasEngine  *engine,
@@ -1034,11 +1030,11 @@ peas_engine_enable_loader (PeasEngine  *engine,
  * peas_engine_get_plugin_list:
  * @engine: A #PeasEngine.
  *
- * Returns the list of #PeasPluginInfo known to the engine.
+ * Returns the list of [struct@PluginInfo] known to the engine.
  *
  * Returns: (transfer none) (element-type Peas.PluginInfo): a #GList of
- * #PeasPluginInfo. Note that the list belongs to the engine and should
- * not be freed.
+ *   #PeasPluginInfo. Note that the list belongs to the engine and should
+ *   not be freed.
  **/
 const GList *
 peas_engine_get_plugin_list (PeasEngine *engine)
@@ -1055,11 +1051,11 @@ peas_engine_get_plugin_list (PeasEngine *engine)
  * @engine: A #PeasEngine.
  * @plugin_name: A plugin name.
  *
- * Gets the #PeasPluginInfo corresponding with @plugin_name,
+ * Gets the [struct@PluginInfo] corresponding with @plugin_name,
  * or %NULL if @plugin_name was not found.
  *
  * Returns: (transfer none): the #PeasPluginInfo corresponding with
- * a given plugin module name.
+ *   a given plugin module name.
  */
 PeasPluginInfo *
 peas_engine_get_plugin_info (PeasEngine  *engine,
@@ -1172,7 +1168,8 @@ error:
  * @info: A #PeasPluginInfo.
  *
  * Loads the plugin corresponding to @info if it's not currently loaded.
- * Emits the "load-plugin" signal; loading the plugin
+ *
+ * Emits the [signal@Engine::load-plugin] signal; loading the plugin
  * actually occurs in the default signal handler.
  *
  * Returns: whether the plugin has been successfully loaded.
@@ -1246,7 +1243,8 @@ peas_engine_unload_plugin_real (PeasEngine     *engine,
  * @info: A #PeasPluginInfo.
  *
  * Unloads the plugin corresponding to @info.
- * Emits the "unload-plugin" signal; unloading the plugin
+ *
+ * Emits the [signal@Engine::unload-plugin] signal; unloading the plugin
  * actually occurs in the default signal handler.
  *
  * Returns: whether the plugin has been successfully unloaded.
@@ -1273,10 +1271,11 @@ peas_engine_unload_plugin (PeasEngine     *engine,
  * @extension_type: The extension #GType.
  *
  * Returns if @info provides an extension for @extension_type.
+ *
  * If the @info is not loaded than %FALSE will always be returned.
  *
- * Since libpeas 1.22, @extension_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @extension_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
  * Returns: if @info provides an extension for @extension_type.
  */
@@ -1310,12 +1309,14 @@ peas_engine_provides_extension (PeasEngine     *engine,
  *
  * If the plugin identified by @info implements the @extension_type,
  * then this function will return a new instance of this implementation,
- * wrapped in a new #PeasExtension instance. Otherwise, it will return %NULL.
+ * wrapped in a new [alias@Extension] instance.
  *
- * Since libpeas 1.22, @extension_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Otherwise, it will return %NULL.
  *
- * See peas_engine_create_extension() for more information.
+ * Since libpeas 1.22, @extension_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
+ *
+ * See [method@Engine.create_extension] for more information.
  *
  * Returns: (transfer full): a new instance of #PeasExtension wrapping
  * the @extension_type instance, or %NULL.
@@ -1362,15 +1363,15 @@ peas_engine_create_extensionv (PeasEngine     *engine,
  *
  * If the plugin identified by @info implements the @extension_type,
  * then this function will return a new instance of this implementation,
- * wrapped in a new #PeasExtension instance. Otherwise, it will return %NULL.
+ * wrapped in a new [alias@Extension] instance. Otherwise, it will return %NULL.
  *
- * Since libpeas 1.22, @extension_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @extension_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
- * See peas_engine_create_extension() for more information.
+ * See [method@Engine.create_extension] for more information.
  *
  * Returns: (transfer full): a new instance of #PeasExtension wrapping
- * the @extension_type instance, or %NULL.
+ *   the @extension_type instance, or %NULL.
  *
  * Since: 1.24
  */
@@ -1439,15 +1440,15 @@ peas_engine_create_extension_with_properties (PeasEngine     *engine,
  *
  * If the plugin identified by @info implements the @extension_type,
  * then this function will return a new instance of this implementation,
- * wrapped in a new #PeasExtension instance. Otherwise, it will return %NULL.
+ * wrapped in a new [alias@Extension] instance. Otherwise, it will return %NULL.
  *
- * Since libpeas 1.22, @extension_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @extension_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
- * See peas_engine_create_extension() for more information.
+ * See [method@Engine.create_extension] for more information.
  *
  * Returns: a new instance of #PeasExtension wrapping
- * the @extension_type instance, or %NULL.
+ *   the @extension_type instance, or %NULL.
  */
 PeasExtension *
 peas_engine_create_extension_valist (PeasEngine     *engine,
@@ -1496,22 +1497,22 @@ peas_engine_create_extension_valist (PeasEngine     *engine,
  *
  * If the plugin identified by @info implements the @extension_type,
  * then this function will return a new instance of this implementation,
- * wrapped in a new #PeasExtension instance. Otherwise, it will return %NULL.
+ * wrapped in a new [alias@Extension] instance. Otherwise, it will return %NULL.
  *
  * When creating the new instance of the @extension_type subtype, the
  * provided construct properties will be passed to the extension construction
- * handler (exactly like if you had called g_object_new() yourself).
+ * handler (exactly like if you had called [ctor GObject Object new] yourself).
  *
  * The new extension instance produced by this function will always be
  * returned wrapped in a #PeasExtension proxy, following the current libpeas
  * principle of never giving you the actual object (also because it might as
  * well *not* be an actual object).
  *
- * Since libpeas 1.22, @extension_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @extension_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
  * Returns: a new instance of #PeasExtension wrapping
- * the @extension_type instance, or %NULL.
+ *   the @extension_type instance, or %NULL.
  */
 PeasExtension *
 peas_engine_create_extension (PeasEngine     *engine,
@@ -1541,14 +1542,16 @@ peas_engine_create_extension (PeasEngine     *engine,
  * peas_engine_get_loaded_plugins:
  * @engine: A #PeasEngine.
  *
- * Returns the list of the names of all the loaded plugins, or an array
- * containing a single %NULL element if there is no plugin currently loaded.
+ * Returns the list of the names of all the loaded plugins.
+ *
+ * If there is no plugin currently loaded, it will return an array containing a
+ * single %NULL element.
  *
  * Please note that the returned array is a newly allocated one: you will need
- * to free it using g_strfreev().
+ * to free it using [func@GLib.strfreev].
  *
  * Returns: (transfer full) (array zero-terminated=1): A newly-allocated
- * %NULL-terminated array of strings.
+ *   %NULL-terminated array of strings.
  */
 gchar **
 peas_engine_get_loaded_plugins (PeasEngine *engine)
@@ -1600,9 +1603,11 @@ string_in_strv (const gchar  *needle,
  * @plugin_names: (allow-none) (array zero-terminated=1): A %NULL-terminated
  *  array of plugin names, or %NULL.
  *
- * Sets the list of loaded plugins for @engine. When this function is called,
- * the #PeasEngine will load all the plugins whose names are in @plugin_names,
- * and ensures all other active plugins are unloaded.
+ * Sets the list of loaded plugins for @engine.
+ *
+ * When this function is called, the #PeasEngine will load all the plugins whose
+ * names are in @plugin_names, and ensures all other active plugins are
+ * unloaded.
  *
  * If @plugin_names is %NULL, all plugins will be unloaded.
  */
@@ -1641,6 +1646,7 @@ peas_engine_set_loaded_plugins (PeasEngine   *engine,
  * peas_engine_new:
  *
  * Return a new instance of #PeasEngine.
+ *
  * If no default #PeasEngine has been instantiated yet,
  * the first call of this function will set the default
  * engine as the new instance of #PeasEngine.
@@ -1657,12 +1663,13 @@ peas_engine_new (void)
  * peas_engine_new_with_nonglobal_loaders:
  *
  * Return a new instance of #PeasEngine which will use non-global
- * plugin loaders instead of the default global ones. This allows
- * multiple threads to each have a #PeasEngine and be used without
+ * plugin loaders instead of the default global ones.
+ *
+ * This allows multiple threads to each have a #PeasEngine and be used without
  * internal locking.
  *
  * Note: due to CPython's GIL the python and python3
- *       plugin loaders are always global.
+ *   plugin loaders are always global.
  *
  * Returns: a new instance of #PeasEngine that uses non-global loaders.
  *
@@ -1680,11 +1687,12 @@ peas_engine_new_with_nonglobal_loaders (void)
  * peas_engine_get_default:
  *
  * Return the existing instance of #PeasEngine or a subclass of it.
+ *
  * If no #PeasEngine subclass has been instantiated yet, the first call
  * of this function will return a new instance of #PeasEngine.
  *
  * Note: this function should never be used when multiple threads are
- *       using libpeas API as it is not thread-safe.
+ *   using libpeas API as it is not thread-safe.
  *
  * Returns: (transfer none): the existing instance of #PeasEngine.
  */
diff --git a/libpeas/peas-extension-base.c b/libpeas/peas-extension-base.c
index c8ecc925..649ed4ab 100644
--- a/libpeas/peas-extension-base.c
+++ b/libpeas/peas-extension-base.c
@@ -26,13 +26,13 @@
 #include "peas-plugin-info-priv.h"
 
 /**
- * SECTION:peas-extension-base
- * @short_description: Base class for C extensions.
- * @see_also: #PeasPluginInfo
+ * PeasExtensionBase:
+ *
+ * Base class for C extensions.
  *
  * #PeasExtensionBase can optionally be used as a base class for the extensions
  * of your plugin. By inheriting from it, you will make your extension able to
- * access the related #PeasPluginInfo, and especially the location where all
+ * access the related [struct@PluginInfo], and especially the location where all
  * the data of your plugin lives.
  *
  * Non-C extensions will usually not inherit from this class: Python
@@ -119,7 +119,7 @@ peas_extension_base_class_init (PeasExtensionBaseClass *klass)
   /**
    * PeasExtensionBase:plugin-info:
    *
-   * The #PeasPluginInfo related to the current plugin.
+   * The [struct@PluginInfo] related to the current plugin.
    */
   properties[PROP_PLUGIN_INFO] =
     g_param_spec_boxed ("plugin-info",
@@ -137,7 +137,7 @@ peas_extension_base_class_init (PeasExtensionBaseClass *klass)
    * should look for its data files.
    *
    * Note: This is the same path as that returned by
-   * peas_plugin_info_get_data_dir().
+   * [method@PluginInfo.get_data_dir].
    */
   properties[PROP_DATA_DIR] =
     g_param_spec_string ("data-dir",
@@ -157,8 +157,8 @@ peas_extension_base_class_init (PeasExtensionBaseClass *klass)
  *
  * Get information relative to @extbase.
  *
- * Return value: (transfer none): the #PeasPluginInfo relative
- * to the #PeasExtensionBase.
+ * Returns: (transfer none): the [struct@PluginInfo] relative
+ *   to the #PeasExtensionBase.
  */
 PeasPluginInfo *
 peas_extension_base_get_plugin_info (PeasExtensionBase *extbase)
@@ -177,8 +177,8 @@ peas_extension_base_get_plugin_info (PeasExtensionBase *extbase)
  * Get the path of the directory where the plugin should look for
  * its data files.
  *
- * Return value: A newly allocated string with the path of the
- * directory where the plugin should look for its data files
+ * Returns: A newly allocated string with the path of the
+ *   directory where the plugin should look for its data files
  */
 gchar *
 peas_extension_base_get_data_dir (PeasExtensionBase *extbase)
diff --git a/libpeas/peas-extension-set.c b/libpeas/peas-extension-set.c
index baeb4a4c..55627e60 100644
--- a/libpeas/peas-extension-set.c
+++ b/libpeas/peas-extension-set.c
@@ -32,9 +32,9 @@
 #include "peas-utils.h"
 
 /**
- * SECTION:peas-extension-set
- * @short_description: Proxy for a set of extensions of the same type.
- * @see_also: #PeasExtension
+ * PeasExtensionSet:
+ *
+ * Proxy for a set of extensions of the same type.
  *
  * A #PeasExtensionSet is an object which proxies method calls to a set
  * of actual extensions.  The application writer will use these objects
@@ -47,9 +47,10 @@
  * wish to call specific methods on loading or unloading time.
  *
  * Here is the code for a typical setup of #PeasExtensionSet with
- * #PeasActivatable as the watched extension point, and #GtkWindow
+ * [iface@Activatable] as the watched extension point, and [class@Gtk.Window]
  * instances as the target objects:
- * |[
+ *
+ * ```c
  * static void
  * on_extension_added (PeasExtensionSet *set,
  *                     PeasPluginInfo   *info,
@@ -83,7 +84,7 @@
  *                     G_CALLBACK (on_extension_removed), NULL);
  *   return set;
  * }
- * ]|
+ * ```
  **/
 
 struct _PeasExtensionSetPrivate {
@@ -360,9 +361,10 @@ peas_extension_set_class_init (PeasExtensionSetClass *klass)
    * @info: A #PeasPluginInfo.
    * @exten: A #PeasExtension.
    *
-   * The extension-added signal is emitted when a new extension has been
-   * added to the #PeasExtensionSet. It happens when a new plugin implementing
-   * the extension set's extension type is loaded.
+   * Emitted when a new extension has been added to the #PeasExtensionSet.
+   *
+   * It happens when a new plugin implementing the extension set's extension
+   * type is loaded.
    *
    * You should connect to this signal in order to set up the extensions when
    * they are loaded. Note that this signal is not fired for extensions coming
@@ -387,14 +389,15 @@ peas_extension_set_class_init (PeasExtensionSetClass *klass)
    * @info: A #PeasPluginInfo.
    * @exten: A #PeasExtension.
    *
-   * The extension-removed signal is emitted when a new extension is about to be
-   * removed from the #PeasExtensionSet. It happens when a plugin implementing
-   * the extension set's extension type is unloaded, or when the
-   * #PeasExtensionSet itself is destroyed.
+   * Emitted when a new extension is about to be removed from the
+   * #PeasExtensionSet.
+   *
+   * It happens when a plugin implementing the extension set's extension type is
+   * unloaded, or when the #PeasExtensionSet itself is destroyed.
    *
    * You should connect to this signal in order to clean up the extensions
    * when their plugin is unload. Note that this signal is not fired for the
-   * #PeasExtension instances still available when the #PeasExtensionSet
+   * [alias@Extension] instances still available when the #PeasExtensionSet
    * instance is destroyed. You should clean those up by yourself.
    */
   signals[EXTENSION_REMOVED] =
@@ -443,10 +446,11 @@ peas_extension_set_class_init (PeasExtensionSetClass *klass)
  * @set: A #PeasExtensionSet
  * @info: a #PeasPluginInfo
  *
- * Returns the #PeasExtension object corresponding to @info, or %NULL
- * if the plugin doesn't provide such an extension.
+ * Returns the [alias@Extension] object corresponding to @info.
+ *
+ * If the plugin doesn't provide such an extension, it returns %NULL.
  *
- * Returns: (transfer none): a reference to a #PeasExtension or %NULL
+ * Returns: (transfer none): a reference to a #PeasExtension
  */
 PeasExtension *
 peas_extension_set_get_extension (PeasExtensionSet *set,
@@ -475,13 +479,13 @@ peas_extension_set_get_extension (PeasExtensionSet *set,
  * @method_name: the name of the method that should be called.
  * @...: arguments for the method.
  *
- * Call a method on all the #PeasExtension instances contained in @set.
+ * Call a method on all the [alias@Extension] instances contained in @set.
  *
- * See peas_extension_call() for more information.
+ * See [method Extension call] for more information.
  *
- * Deprecated: 1.2: Use peas_extension_set_foreach() instead.
+ * Deprecated: 1.2: Use [method@ExtensionSet.foreach] instead.
  *
- * Return value: %TRUE on successful call.
+ * Returns: %TRUE on successful call.
  */
 gboolean
 peas_extension_set_call (PeasExtensionSet *set,
@@ -507,13 +511,13 @@ peas_extension_set_call (PeasExtensionSet *set,
  * @method_name: the name of the method that should be called.
  * @va_args: the arguments for the method.
  *
- * Call a method on all the #PeasExtension instances contained in @set.
+ * Call a method on all the [alias@Extension] instances contained in @set.
  *
- * See peas_extension_call_valist() for more information.
+ * See [method@Extension.call_valist] for more information.
  *
- * Deprecated: 1.2: Use peas_extension_set_foreach() instead.
+ * Deprecated: 1.2: Use [class@ExtensionSet.foreach] instead.
  *
- * Return value: %TRUE on successful call.
+ * Returns: %TRUE on successful call.
  */
 gboolean
 peas_extension_set_call_valist (PeasExtensionSet *set,
@@ -554,13 +558,13 @@ peas_extension_set_call_valist (PeasExtensionSet *set,
  * @method_name: the name of the method that should be called.
  * @args: the arguments for the method.
  *
- * Call a method on all the #PeasExtension instances contained in @set.
+ * Call a method on all the [alias@Extension] instances contained in @set.
  *
- * See peas_extension_callv() for more information.
+ * See [method@Extension.callv] for more information.
  *
- * Return value: %TRUE on successful call.
+ * Returns: %TRUE on successful call.
  *
- * Deprecated: 1.2: Use peas_extension_set_foreach() instead.
+ * Deprecated: 1.2: Use [method@ExtensionSet.foreach] instead.
  */
 gboolean
 peas_extension_set_callv (PeasExtensionSet *set,
@@ -582,7 +586,7 @@ peas_extension_set_callv (PeasExtensionSet *set,
  * @func: (scope call): A function call for each extension.
  * @data: Optional data to be passed to the function or %NULL.
  *
- * Calls @func for each #PeasExtension.
+ * Calls @func for each [alias@Extension].
  *
  * Since: 1.2
  */
@@ -616,10 +620,10 @@ peas_extension_set_foreach (PeasExtensionSet            *set,
  *
  * If @engine is %NULL, then the default engine will be used.
  *
- * Since libpeas 1.22, @exten_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @exten_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
- * See peas_extension_set_new() for more information.
+ * See [ctor ExtensionSet new] for more information.
  *
  * Returns: (transfer full): a new instance of #PeasExtensionSet.
  */
@@ -654,10 +658,10 @@ peas_extension_set_newv (PeasEngine *engine,
  *
  * If @engine is %NULL, then the default engine will be used.
  *
- * Since libpeas 1.22, @exten_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @exten_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
- * See peas_extension_set_new() for more information.
+ * See [ctor ExtensionSet new] for more information.
  *
  * Returns: (transfer full): a new instance of #PeasExtensionSet.
  *
@@ -720,10 +724,10 @@ peas_extension_set_new_with_properties (PeasEngine    *engine,
  *
  * If @engine is %NULL, then the default engine will be used.
  *
- * Since libpeas 1.22, @exten_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @exten_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
- * See peas_extension_set_new() for more information.
+ * See [ctor ExtensionSet new] for more information.
  *
  * Returns: a new instance of #PeasExtensionSet.
  */
@@ -770,17 +774,17 @@ peas_extension_set_new_valist (PeasEngine  *engine,
  *
  * At any moment, the #PeasExtensionSet will contain an extension instance for
  * each loaded plugin which implements the @exten_type extension type. It does
- * so by connecting to the relevant signals from #PeasEngine.
+ * so by connecting to the relevant signals from [class@Engine].
  *
  * The property values passed to peas_extension_set_new() will be used for the
  * construction of new extension instances.
  *
  * If @engine is %NULL, then the default engine will be used.
  *
- * Since libpeas 1.22, @exten_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @exten_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
- * See peas_engine_create_extension() for more information.
+ * See [method@Engine.create_extension] for more information.
  *
  * Returns: a new instance of #PeasExtensionSet.
  */
diff --git a/libpeas/peas-extension-set.h b/libpeas/peas-extension-set.h
index 2d18595e..5f83851b 100644
--- a/libpeas/peas-extension-set.h
+++ b/libpeas/peas-extension-set.h
@@ -99,7 +99,7 @@ struct _PeasExtensionSetClass {
  * @exten: A #PeasExtension.
  * @data: Optional data passed to the function.
  *
- * This function is passed to peas_extension_set_foreach() and
+ * This function is passed to [method@ExtensionSet.foreach] and
  * will be called for each extension in @set.
  *
  * Since: 1.2
diff --git a/libpeas/peas-extension.c b/libpeas/peas-extension.c
index 79344d9c..5d156074 100644
--- a/libpeas/peas-extension.c
+++ b/libpeas/peas-extension.c
@@ -25,25 +25,24 @@
 #include "peas-introspection.h"
 
 /**
- * SECTION:peas-extension
- * @short_description: Proxy for extensions.
- * @see_also: #PeasExtensionSet
+ * PeasExtension:
  *
- * #PeasExtension is a proxy class used to access actual extensions
- * implemented using various languages.  As such, the application writer will
- * use #PeasExtension instances to call methods on extension provided by
- * loaded plugins.
+ * #PeasExtension is a proxy class used to access actual extensions implemented
+ * using various languages.
+ *
+ * As such, the application writer will use #PeasExtension instances to call
+ * methods on extension provided by loaded plugins.
  *
  * To properly use the proxy instances, you will need GObject-introspection
- * data for the #GType you want to use as an extension point.
- * For instance, if you wish to use #PeasActivatable, you will need to
+ * data for the [alias GObject Type] you want to use as an extension point.
+ * For instance, if you wish to use [iface@Activatable], you will need to
  * put the following code excerpt in the engine initialization code, in order
  * to load the required "Peas" typelib:
  *
- * |[
+ * ```c
  * g_irepository_require (g_irepository_get_default (),
  *                        "Peas", "1.0", 0, NULL);
- * ]|
+ * ```
  *
  * You should proceed the same way for any namespace which provides types
  * you want to use as extension points. GObject-introspection data is required
@@ -56,7 +55,7 @@
  * Another reason is that it makes reference counting issues easier to deal
  * with.
  *
- * See peas_extension_call() for more information.
+ * See [method@extension_call] for more information.
  **/
 GType
 peas_extension_get_type (void)
@@ -115,9 +114,9 @@ get_method_info (PeasExtension *exten,
  * peas_extension_get_extension_type:
  * @exten: A #PeasExtension.
  *
- * Get the #GType of the extension proxied by @exten.
+ * Get the [alias GObject Type] of the extension proxied by @exten.
  *
- * Return value: The #GType proxied by @exten.
+ * Returns: The #GType proxied by @exten.
  *
  * Deprecated: 1.2.
  */
@@ -150,7 +149,7 @@ peas_extension_get_extension_type (PeasExtension *exten)
  * This function will not do anything if the introspection data for the proxied
  * object's class has not been loaded previously through g_irepository_require().
  *
- * Return value: %TRUE on successful call.
+ * Returns: %TRUE on successful call.
  *
  * Deprecated: 1.2: Use the object directly instead.
  */
@@ -182,7 +181,7 @@ peas_extension_call (PeasExtension *exten,
  *
  * See peas_extension_call() for more information.
  *
- * Return value: %TRUE on successful call.
+ * Returns: %TRUE on successful call.
  *
  * Deprecated: 1.2: Use the object directly instead.
  */
@@ -237,7 +236,7 @@ peas_extension_call_valist (PeasExtension *exten,
  *
  * See peas_extension_call() for more information.
  *
- * Return value: %TRUE on successful call.
+ * Returns: %TRUE on successful call.
  *
  * Deprecated: 1.2: Use the object directly instead.
  */
diff --git a/libpeas/peas-object-module.c b/libpeas/peas-object-module.c
index d48b6fbf..0f38fd51 100644
--- a/libpeas/peas-object-module.c
+++ b/libpeas/peas-object-module.c
@@ -31,16 +31,17 @@
 #include "peas-plugin-loader.h"
 
 /**
- * SECTION:peas-object-module
- * @short_description: Type module which allows extension registration.
+ * PeasObjectModule:
  *
- * #PeasObjectModule is a subclass of #GTypeModule which allows registration
- * of extensions.  It will be used by C extensions implementors to register
- * extension implementations from within the peas_register_types module
+ * Type module which allows extension registration.
+ *
+ * #PeasObjectModule is a subclass of [class@GObject.TypeModule] which allows
+ * registration of extensions. It will be used by C extensions implementors to
+ * register extension implementations from within the peas_register_types module
  * function.
  *
- * Since libpeas 1.22, @extension_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @extension_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  **/
 
 typedef void (*PeasObjectModuleRegisterFunc) (PeasObjectModule *module);
@@ -361,8 +362,7 @@ peas_object_module_class_init (PeasObjectModuleClass *klass)
   /**
    * PeasObjectModule:local-linkage
    *
-   * This property indicates whether the module is loaded with
-   * local linkage, i.e. #G_MODULE_BIND_LOCAL.
+   * Whether the module is loaded with local linkage, i.e. #G_MODULE_BIND_LOCAL.
    *
    * Since 1.14
    */
@@ -386,7 +386,7 @@ peas_object_module_class_init (PeasObjectModuleClass *klass)
  *
  * Creates a new #PeasObjectModule.
  *
- * Return value: a new #PeasObjectModule.
+ * Returns: a new #PeasObjectModule.
  */
 PeasObjectModule *
 peas_object_module_new (const gchar *module_name,
@@ -412,7 +412,7 @@ peas_object_module_new (const gchar *module_name,
  *
  * Creates a new #PeasObjectModule.
  *
- * Return value: a new #PeasObjectModule.
+ * Returns: a new #PeasObjectModule.
  *
  * Since 1.14
  */
@@ -439,7 +439,7 @@ peas_object_module_new_full (const gchar *module_name,
  *
  * Creates a new #PeasObjectModule for an embedded plugin.
  *
- * Return value: a new #PeasObjectModule.
+ * Returns: a new #PeasObjectModule.
  *
  * Since: 1.18
  */
@@ -466,14 +466,15 @@ peas_object_module_new_embedded (const gchar *module_name,
  * @parameters: (array length=n_parameters): The parameters.
  *
  * Creates an object for the @exten_type passing @n_parameters
- * and @parameters to the #PeasFactoryFunc. If @module does
- * not provide a #PeasFactoryFunc for @exten_type then
- * %NULL is returned.
+ * and @parameters to the [callback@FactoryFunc].
+ *
+ * If @module does not provide a #PeasFactoryFunc for @exten_type then %NULL is
+ * returned.
  *
- * Since libpeas 1.22, @exten_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @exten_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
- * Return value: (transfer full): The created object, or %NULL.
+ * Returns: (transfer full): The created object
  */
 GObject *
 peas_object_module_create_object (PeasObjectModule *module,
@@ -506,10 +507,10 @@ peas_object_module_create_object (PeasObjectModule *module,
  *
  * Determines if the module provides an extension for @exten_type.
  *
- * Since libpeas 1.22, @exten_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @exten_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  *
- * Return value: if the module provides an extension for @exten_type.
+ * Returns: if the module provides an extension for @exten_type.
  */
 gboolean
 peas_object_module_provides_object (PeasObjectModule *module,
@@ -539,7 +540,7 @@ peas_object_module_provides_object (PeasObjectModule *module,
  *
  * Gets the path.
  *
- * Return value: the path.
+ * Returns: the path.
  */
 const gchar *
 peas_object_module_get_path (PeasObjectModule *module)
@@ -557,7 +558,7 @@ peas_object_module_get_path (PeasObjectModule *module)
  *
  * Gets the module name.
  *
- * Return value: the module name.
+ * Returns: the module name.
  */
 const gchar *
 peas_object_module_get_module_name (PeasObjectModule *module)
@@ -575,7 +576,7 @@ peas_object_module_get_module_name (PeasObjectModule *module)
  *
  * Gets the symbol name used to register extension implementations.
  *
- * Return value: the symbol name.
+ * Returns: the symbol name.
  *
  * Since: 1.18
  */
@@ -595,7 +596,7 @@ peas_object_module_get_symbol (PeasObjectModule *module)
  *
  * Gets the library.
  *
- * Return value: the library.
+ * Returns: the library.
  */
 GModule *
 peas_object_module_get_library (PeasObjectModule *module)
@@ -622,11 +623,11 @@ peas_object_module_get_library (PeasObjectModule *module)
  *
  * This method is primarily meant to be used by native bindings (like gtkmm),
  * creating native types which cannot be instantiated correctly using
- * g_object_new().  For other uses, you will usually prefer relying on
+ * [ctor GObject Object new].  For other uses, you will usually prefer relying on
  * peas_object_module_register_extension_type().
  *
- * Since libpeas 1.22, @exten_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @exten_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  */
 void
 peas_object_module_register_extension_factory (PeasObjectModule *module,
@@ -687,8 +688,8 @@ create_gobject_from_type (guint       n_parameters,
  *
  * Register @impl_type as an extension which implements @extension_type.
  *
- * Since libpeas 1.22, @exten_type can be an Abstract #GType
- * and not just an Interface #GType.
+ * Since libpeas 1.22, @exten_type can be an Abstract [alias GObject Type]
+ * and not just an Interface [alias GObject Type].
  */
 void
 peas_object_module_register_extension_type (PeasObjectModule *module,
diff --git a/libpeas/peas-object-module.h b/libpeas/peas-object-module.h
index 986d2de0..b06d20b0 100644
--- a/libpeas/peas-object-module.h
+++ b/libpeas/peas-object-module.h
@@ -51,11 +51,11 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * @user_data: Optional data to be passed to the function, or %NULL.
  *
  * A #PeasFactoryFunc is a factory function which will instanciate a new
- * extension of a given type. g_object_newv() is such a function.
+ * extension of a given type. [ctor GObject Object newv] is such a function.
  *
- * It is used with peas_object_module_register_extension_factory().
+ * It is used with [method@ObjectModule.register_extension_factory].
  *
- * Return value: (transfer full): The created object.
+ * Returns: (transfer full): The created object.
  */
 typedef GObject *(*PeasFactoryFunc)   (guint          n_parameters,
                                        GParameter    *parameters,
diff --git a/libpeas/peas-plugin-info.c b/libpeas/peas-plugin-info.c
index 6040004c..e3ea06f9 100644
--- a/libpeas/peas-plugin-info.c
+++ b/libpeas/peas-plugin-info.c
@@ -37,15 +37,15 @@
 #endif
 
 /**
- * SECTION:peas-plugin-info
- * @short_description: Information about a plugin.
+ * PeasPluginInfo:
  *
  * A #PeasPluginInfo contains all the information available about a plugin.
  *
  * All this information comes from the related plugin info file, whose file
  * extension is ".plugin". Here is an example of such a plugin file, in the
- * #GKeyFile format:
- * |[
+ * [struct@GLib.KeyFile] format:
+ *
+ * ```toml
  * [Plugin]
  * Module=helloworld
  * Depends=foo;bar;baz
@@ -57,7 +57,7 @@
  * Website=https://wiki.gnome.org/Projects/Libpeas
  * Help=http://library.gnome.org/devel/libpeas/stable/
  * Hidden=false
- * ]|
+ * ```
  **/
 
 G_DEFINE_QUARK (peas-plugin-info-error, peas_plugin_info_error)
@@ -114,7 +114,7 @@ _peas_plugin_info_unref (PeasPluginInfo *info)
  *
  * Creates a new #PeasPluginInfo from a file on the disk.
  *
- * Return value: a newly created #PeasPluginInfo.
+ * Returns: a newly created #PeasPluginInfo.
  */
 PeasPluginInfo *
 _peas_plugin_info_new (const gchar *filename,
@@ -382,16 +382,17 @@ peas_plugin_info_is_available (const PeasPluginInfo  *info,
  *
  * Check if the plugin is a builtin plugin.
  *
- * A builtin plugin is a plugin which cannot be enabled or disabled by the
- * user through a plugin manager (like #PeasGtkPluginManager). Loading or
- * unloading such plugins is the responsibility of the application alone.
- * Most applications will usually load those plugins immediately after
+ * A builtin plugin is a plugin which cannot be enabled or disabled by the user
+ * through a plugin manager (like
+ * 
[PeasGtkPluginManager](https://gnome.pages.gitlab.gnome.org/libpeas/libpeas-gtk-1.0/class.PluginManager.html)).
+ * Loading or unloading such plugins is the responsibility of the application
+ * alone. Most applications will usually load those plugins immediately after
  * the initialization of the #PeasEngine.
  *
  * The relevant key in the plugin info file is "Builtin".
  *
  * Returns: %TRUE if the plugin is a builtin plugin, %FALSE
- * if not.
+ *   if not.
  **/
 gboolean
 peas_plugin_info_is_builtin (const PeasPluginInfo *info)
@@ -408,14 +409,16 @@ peas_plugin_info_is_builtin (const PeasPluginInfo *info)
  * Check if the plugin is a hidden plugin.
  *
  * A hidden plugin is a plugin which cannot be seen by a
- * user through a plugin manager (like #PeasGtkPluginManager). Loading and
+ * user through a plugin manager (like
+ * 
[PeasGtkPluginManager](https://gnome.pages.gitlab.gnome.org/libpeas/libpeas-gtk-1.0/class.PluginManager.html)).
+ * Loading and
  * unloading such plugins is the responsibility of the application alone or
  * through plugins that depend on them.
  *
  * The relevant key in the plugin info file is "Hidden".
  *
  * Returns: %TRUE if the plugin is a hidden plugin, %FALSE
- * if not.
+ *   if not.
  **/
 gboolean
 peas_plugin_info_is_hidden (const PeasPluginInfo *info)
@@ -454,8 +457,8 @@ peas_plugin_info_get_module_name (const PeasPluginInfo *info)
  * Gets the module directory.
  *
  * The module directory is the directory where the plugin file was found. This
- * is not a value from the #GKeyFile, but rather a value provided by the
- * #PeasEngine.
+ * is not a value from the [struct@GLib.KeyFile], but rather a value provided by the
+ * [class@Engine].
  *
  * Returns: the module directory.
  */
@@ -474,9 +477,9 @@ peas_plugin_info_get_module_dir (const PeasPluginInfo *info)
  * Gets the data dir of the plugin.
  *
  * The module data directory is the directory where a plugin should find its
- * runtime data. This is not a value read from the #GKeyFile, but rather a
- * value provided by the #PeasEngine, depending on where the plugin file was
- * found.
+ * runtime data. This is not a value read from the [struct@GLib.KeyFile], but
+ * rather a value provided by the [class@Engine], depending on where the plugin
+ * file was found.
  *
  * Returns: the plugin's data dir.
  */
@@ -493,7 +496,7 @@ peas_plugin_info_get_data_dir (const PeasPluginInfo *info)
  * @info: A #PeasPluginInfo.
  * @schema_id: (allow-none): The schema id.
  *
- * Creates a new #GSettings for the given @schema_id and if
+ * Creates a new [class@Gio.Settings] for the given @schema_id and if
  * gschemas.compiled is not in the module directory an attempt
  * will be made to create it.
  *
@@ -569,7 +572,7 @@ peas_plugin_info_get_settings (const PeasPluginInfo *info,
  *
  * Gets the dependencies of the plugin.
  *
- * The #PeasEngine will always ensure that the dependencies of a plugin are
+ * The [class@Engine] will always ensure that the dependencies of a plugin are
  * loaded when the said plugin is loaded. It means that dependencies are
  * loaded before the plugin, and unloaded after it. Circular dependencies of
  * plugins lead to undefined loading order.
@@ -783,7 +786,7 @@ peas_plugin_info_get_help_uri (const PeasPluginInfo *info)
  * Gets external data specified for the plugin.
  *
  * External data is specified in the plugin info file prefixed with X-. For
- * example, if a key/value pair X-Peas=1 is specified in the key file, you
+ * example, if a key/value pair `X-Peas=1` is specified in the key file, you
  * can use "Peas" for @key to retrieve the value "1".
  *
  * Note: that you can omit the X- prefix when retrieving the value,
diff --git a/libpeas/peas-version.h.in b/libpeas/peas-version.h.in
index 854b60a9..a818955a 100644
--- a/libpeas/peas-version.h.in
+++ b/libpeas/peas-version.h.in
@@ -20,13 +20,6 @@
 #ifndef __PEAS_VERSION_H__
 #define __PEAS_VERSION_H__
 
-/**
- * SECTION:peas-version
- * @short_description: Peas version checking
- *
- * Peas provides macros to check the version of the library at compile-time
- */
-
 /**
  * PEAS_MAJOR_VERSION:
  *
@@ -49,7 +42,7 @@
 #define PEAS_MICRO_VERSION              (@PEAS_MICRO_VERSION@)
 
 /**
- * PEAS_VERSION
+ * PEAS_VERSION:
  *
  * Peas version.
  */


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]