docs: Port from gtk-doc to gi-docgen

gtk-doc has been slowly dying for the past few years. With gi-docgen we
have a clear successor in sight to replace the voodoo magic one needs to
get the whole documentation setup.

See the [gi-docgen tutorial] for more info on how the system works.

Since we're now only the C compiler (and GIR) parse the C code, that
means we can also get rid of all the special escapes for the # character
in PKCS#11.

[gi-docgen tutorial]: https://gnome.pages.gitlab.gnome.org/gi-docgen/tutorial.html

24 files changed, 222 insertions, 514 deletions

diff --git a/gcr/gcr-certificate-chain.c b/gcr/gcr-certificate-chain.c
index 1793869..f34eae8 100644
--- a/gcr/gcr-certificate-chain.c
+++ b/gcr/gcr-certificate-chain.c
@@ -33,11 +33,9 @@
 #include "egg/egg-error.h"
 
 /**
- * SECTION:gcr-certificate-chain
- * @title: GcrCertificateChain
- * @short_description: A certificate chain
+ * GcrCertificateChain:
  *
- * #GcrCertificateChain represents a chain of certificates, normally used to
+ * Represents a chain of certificates, normally used to
  * validate the trust in a certificate. An X.509 certificate chain has one
  * endpoint certificate (the one for which trust is being verified) and then
  * in turn the certificate that issued each previous certificate in the chain.
@@ -49,32 +47,25 @@
  * The order of certificates in the chain should be first the endpoint
  * certificates and then the signing certificates.
  *
- * Create a new certificate chain with gcr_certificate_chain_new() and then
- * add the certificates with gcr_certificate_chain_add().
+ * Create a new certificate chain with [ctor@CertificateChain.new] and then
+ * add the certificates with [method@CertificateChain.add].
  *
- * You can then use gcr_certificate_chain_build() to build the remainder of
- * the chain. This will lookup missing certificates in PKCS\#11 modules and
+ * You can then use [method@CertificateChain.build] to build the remainder of
+ * the chain. This will lookup missing certificates in PKCS#11 modules and
  * also check that each certificate in the chain is the signer of the previous
  * one. If a trust anchor, pinned certificate, or self-signed certificate is
  * found, then the chain is considered built. Any extra certificates are
  * removed from the chain.
  *
  * Once the certificate chain has been built, you can access its status
- * through gcr_certificate_chain_get_status(). The status signifies whether
+ * through [method@CertificateChain.get_status]. The status signifies whether
  * the chain is anchored on a trust root, self-signed, incomplete etc. See
- * #GcrCertificateChainStatus for information on the various statuses.
+ * [enum@CertificateChainStatus] for information on the various statuses.
  *
  * It's important to understand that the building of a certificate chain is
  * merely the first step towards verifying trust in a certificate.
  */
 
-
-/**
- * GcrCertificateChain:
- *
- * A chain of certificates.
- */
-
 /**
  * GcrCertificateChainClass:
  * @parent_class: The parent class
@@ -518,7 +509,7 @@ gcr_certificate_chain_class_init (GcrCertificateChainClass *klass)
  * @GCR_CERTIFICATE_CHAIN_NO_LOOKUPS: If this flag is specified then no
  * lookups for anchors or pinned certificates are done, and the resulting chain
  * will be neither anchored or pinned. Additionally no missing certificate
- * authorities are looked up in PKCS\#11.
+ * authorities are looked up in PKCS#11.
  *
  * Flags to be used with the gcr_certificate_chain_build() operation.
  */
@@ -677,7 +668,7 @@ gcr_certificate_chain_get_certificate (GcrCertificateChain *self, guint index)
  * Complete a certificate chain. Once a certificate chain has been built
  * its status can be examined.
  *
- * This operation will lookup missing certificates in PKCS\#11
+ * This operation will lookup missing certificates in PKCS#11
  * modules and also that each certificate in the chain is the signer of the
  * previous one. If a trust anchor, pinned certificate, or self-signed certificate
  * is found, then the chain is considered built. Any extra certificates are
@@ -699,7 +690,7 @@ gcr_certificate_chain_get_certificate (GcrCertificateChain *self, guint index)
  * If the %GCR_CERTIFICATE_CHAIN_NO_LOOKUPS flag is specified then no
  * lookups for anchors or pinned certificates are done, and the resulting chain
  * will be neither anchored or pinned. Additionally no missing certificate
- * authorities are looked up in PKCS\#11
+ * authorities are looked up in PKCS#11
  *
  * This call will block, see gcr_certificate_chain_build_async() for the
  * asynchronous version.
@@ -749,7 +740,7 @@ gcr_certificate_chain_build (GcrCertificateChain *self,
  * Complete a certificate chain. Once a certificate chain has been built
  * its status can be examined.
  *
- * This will lookup missing certificates in PKCS\#11
+ * This will lookup missing certificates in PKCS#11
  * modules and also that each certificate in the chain is the signer of the
  * previous one. If a trust anchor, pinned certificate, or self-signed certificate
  * is found, then the chain is considered built. Any extra certificates are
@@ -771,7 +762,7 @@ gcr_certificate_chain_build (GcrCertificateChain *self,
  * If the %GCR_CERTIFICATE_CHAIN_NO_LOOKUPS flag is specified then no
  * lookups for anchors or pinned certificates are done, and the resulting chain
  * will be neither anchored or pinned. Additionally no missing certificate
- * authorities are looked up in PKCS\#11
+ * authorities are looked up in PKCS#11
  *
  * When the operation is finished, @callback will be called. You can then call
  * gcr_certificate_chain_build_finish() to get the result of the operation.
diff --git a/gcr/gcr-certificate-request.c b/gcr/gcr-certificate-request.c
index 9736ce8..dc3e936 100644
--- a/gcr/gcr-certificate-request.c
+++ b/gcr/gcr-certificate-request.c
@@ -34,31 +34,22 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-certificate-request
- * @title: GcrCertificateRequest
- * @short_description: Represents a certificate request
+ * GcrCertificateRequest:
  *
- * This is an object that allows creation of certificate requests. A
- * certificate request is sent to a certificate authority to request an
- * X.509 certificate.
+ * An object that allows creation of certificate requests. A certificate
+ * request is sent to a certificate authority to request an X.509 certificate.
  *
- * Use gcr_certificate_request_prepare() to create a blank certificate
+ * Use [ctor@CertificateRequest.prepare] to create a blank certificate
  * request for a given private key. Set the common name on the certificate
- * request with gcr_certificate_request_set_cn(), and then sign the request
- * with gcr_certificate_request_complete_async().
- */
-
-/**
- * GcrCertificateRequest:
- *
- * Represents a certificate request.
+ * request with [method@CertificateRequest.set_cn], and then sign the request
+ * with [method@CertificateRequest.complete_async].
  */
 
 /**
  * GcrCertificateRequestFormat:
- * @GCR_CERTIFICATE_REQUEST_PKCS10: certificate request is in PKCS\#10 format
+ * @GCR_CERTIFICATE_REQUEST_PKCS10: certificate request is in PKCS#10 format
  *
- * The format of a certificate request. Currently only PKCS\#10 is supported.
+ * The format of a certificate request. Currently only PKCS#10 is supported.
  */
 
 struct _GcrCertificateRequest {
@@ -211,7 +202,7 @@ gcr_certificate_request_class_init (GcrCertificateRequestClass *klass)
 }
 
 /**
- * gcr_certificate_request_prepare:
+ * gcr_certificate_request_prepare: (constructor)
  * @format: the format for the certificate request
  * @private_key: the private key the the certificate is being requested for
  *
@@ -693,12 +684,13 @@ gcr_certificate_request_complete_finish (GcrCertificateRequest *self,
  * @length: location to place length of returned data
  *
  * Encode the certificate request. It must have been completed with
- * gcr_certificate_request_complete() or gcr_certificate_request_complete_async()
+ * [method@CertificateRequest.complete] or
+ * [method@CertificateRequest.complete_async].
  *
  * If @textual is %FALSE, the output is a DER encoded certificate request.
  *
- * If @textual is %TRUE, the output is encoded as text. For PKCS\#10 requests this
- * is done using the OpenSSL style PEM encoding.
+ * If @textual is %TRUE, the output is encoded as text. For PKCS#10 requests
+ * this is done using the OpenSSL style PEM encoding.
  *
  * Returns: (transfer full) (array length=length): the encoded certificate request
  */
@@ -742,10 +734,10 @@ gcr_certificate_request_encode (GcrCertificateRequest *self,
 /**
  * gcr_certificate_request_capable:
  * @private_key: a private key
- * @cancellable: cancellation object
+ * @cancellable: (nullable): cancellation object
  * @error: location to place an error
  *
- * Check whether #GcrCertificateRequest is capable of creating a request
+ * Check whether [class@CertificateRequest] is capable of creating a request
  * for the given @private_key.
  *
  * Returns: whether a request can be created
@@ -767,12 +759,12 @@ gcr_certificate_request_capable (GckObject *private_key,
 /**
  * gcr_certificate_request_capable_async:
  * @private_key: a private key
- * @cancellable: cancellation object
+ * @cancellable: (nullable): cancellation object
  * @callback: will be called when the operation completes
  * @user_data: data to be passed to callback
  *
- * Asynchronously check whether #GcrCertificateRequest is capable of creating
- * a request for the given @private_key.
+ * Asynchronously check whether [class@CertificateRequest] is capable of
+ * creating a request for the given @private_key.
  */
 void
 gcr_certificate_request_capable_async (GckObject *private_key,
@@ -794,7 +786,7 @@ gcr_certificate_request_capable_async (GckObject *private_key,
  * @result: asynchronous result
  * @error: location to place an error
  *
- * Get the result for asynchronously check whether #GcrCertificateRequest is
+ * Get the result for asynchronously check whether [class@CertificateRequest] is
  * capable of creating a request for the given @private_key.
  *
  * Returns: whether a request can be created
diff --git a/gcr/gcr-certificate.c b/gcr/gcr-certificate.c
index 22bfabb..dd2b666 100644
--- a/gcr/gcr-certificate.c
+++ b/gcr/gcr-certificate.c
@@ -37,19 +37,18 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-certificate
- * @title: GcrCertificate
- * @short_description: Represents an X.509 certificate
+ * GcrCertificate:
  *
- * This is an interface that represents an X.509 certificate. Objects can
- * implement this interface to make a certificate usable with the GCR
- * library.
+ * An interface that represents an X.509 certificate.
+ *
+ * Objects can implement this interface to make a certificate usable with the
+ * GCR library.
  *
  * Various methods are available to parse out relevant bits of the certificate.
  * However no verification of the validity of a certificate is done here. Use
  * your favorite crypto library to do this.
  *
- * You can use #GcrSimpleCertificate to simply load a certificate for which
+ * You can use [class@SimpleCertificate] to simply load a certificate for which
  * you already have the raw certificate data.
  *
  * The #GcrCertificate interface has several properties that must be implemented.
@@ -63,12 +62,6 @@
  */
 
 /**
- * GcrCertificate:
- *
- * An object which holds a certificate.
- */
-
-/**
  * GcrCertificateIface:
  * @parent: the parent interface type
  * @get_der_data: a method which returns the RAW der data of the certificate
@@ -80,7 +73,7 @@
  * GCR_CERTIFICATE_COLUMNS:
  *
  * The columns that are valid for a certificate. This is to be used with
- * the #GcrTreeSelector or #GcrCollectionModel.
+ * the [class@TreeSelector] or [class@CollectionModel].
  *
  * This is an array of #GcrColumn, owned by the gcr library.
  */
diff --git a/gcr/gcr-collection.c b/gcr/gcr-collection.c
index 5d9ff69..c4c05e5 100644
--- a/gcr/gcr-collection.c
+++ b/gcr/gcr-collection.c
@@ -22,22 +22,15 @@
 #include "gcr-collection.h"
 
 /**
- * SECTION:gcr-collection
- * @title: GcrCollection
- * @short_description: A collection of objects.
- *
- * A #GcrCollection is used to group a set of objects. This is an abstract
- * interface which can be used to determine which objects show up in a selector
- * or other user interface element.
- *
- * Use gcr_simple_collection_new() to create a concrete implementation of this
- * interface which you can add objects to.
- */
-
-/**
  * GcrCollection:
  *
  * A #GcrCollection is used to group a set of objects.
+ *
+ * This is an abstract interface which can be used to determine which objects
+ * show up in a selector or other user interface element.
+ *
+ * Use [ctor@SimpleCollection.new] to create a concrete implementation of this
+ * interface which you can add objects to.
  */
 
 enum {
diff --git a/gcr/gcr-column.c b/gcr/gcr-column.c
index e7e1b6e..099e78e 100644
--- a/gcr/gcr-column.c
+++ b/gcr/gcr-column.c
@@ -24,21 +24,12 @@
 #include "gcr-column.h"
 
 /**
- * SECTION:gcr-column
- * @title: GcrColumn
- * @short_description: Column information for selector or model.
- *
- * A #GcrColumn is used with #GcrTreeSelector or #GcrCollectionModel to define
- * the columns to display.
- */
-
-/**
  * GcrColumnFlags:
  * @GCR_COLUMN_NONE: No column flags
  * @GCR_COLUMN_HIDDEN: Don't display this column.
  * @GCR_COLUMN_SORTABLE: This column is sortable.
  *
- * Flags to be used with #GcrColumn
+ * Flags to be used with a [struct@Column].
  */
 
 /**
@@ -53,12 +44,13 @@
  *     are the same.
  * @user_data: User data associated with the column
  *
- * Represents a column to display in a #GcrCollectionModel or #GcrTreeSelector.
+ * Represents a column to display in a `GcrCollectionModel` or
+ * `GcrTreeSelector`.
  *
  * The label should be set as a translatable string with a context of
- * <code>"column"</code>. This should be done with with this macro:
+ * `"column"`. This should be done with with this macro:
  *
- * <informalexample><programlisting>
+ * ```
  * NC_("column", "My Column Name")
- * </programlisting></informalexample>
+ * ```
  */
diff --git a/gcr/gcr-comparable.c b/gcr/gcr-comparable.c
index e2de7e0..91d54e9 100644
--- a/gcr/gcr-comparable.c
+++ b/gcr/gcr-comparable.c
@@ -24,18 +24,9 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-comparable
- * @title: GcrComparable
- * @short_description: Interface for comparing objects
- *
- * The #GcrComparable interface is implemented by objects when they should be
- * comparable against one another.
- */
-
-/**
  * GcrComparable:
  *
- * The #GcrComparable interface is implemented by comparable objects.
+ * An interface for comparing objects
  */
 
 /**
@@ -43,7 +34,7 @@
  * @parent: type interface
  * @compare: Compare whether tow objects represent the same thing.
  *
- * The interface to implement for #GcrComparable
+ * The interface to implement for [iface@Comparable]
  */
 
 typedef GcrComparableIface GcrComparableInterface;
diff --git a/gcr/gcr-filter-collection.c b/gcr/gcr-filter-collection.c
index c82ec83..c62abae 100644
--- a/gcr/gcr-filter-collection.c
+++ b/gcr/gcr-filter-collection.c
@@ -25,12 +25,12 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-filter-collection
- * @title: GcrFilterCollection
- * @short_description: A collection which filters a GcrCollection
+ * GcrFilterCollection:
+ *
+ * A collection which filters a [iface@Collection].
  *
- * An implementation of #GcrCollection which filters objects from another
- * underlying collection. Use gcr_filter_collection_new_with_callback()
+ * An implementation of [iface@Collection] which filters objects from another
+ * underlying collection. Use [ctor@FilterCollection.new_with_callback]
  * to create a new filter collection.
  *
  * The callback will determine the criteria for whether an object shows through
@@ -38,16 +38,10 @@
  */
 
 /**
- * GcrFilterCollection:
- *
- * A filter implementation of #GcrCollection.
- */
-
-/**
  * GcrFilterCollectionClass:
  * @parent_class: the parent class
  *
- * The class for #GcrFilterCollection.
+ * The class struct for [class@FilterCollection].
  */
 
 /**
@@ -55,7 +49,7 @@
  * @object: object to filter
  * @user_data: user data passed to the callback
  *
- * A function which is called by #GcrFilterCollection in order to determine
+ * A function which is called by [class@FilterCollection] in order to determine
  * whether an object should show through the filter or not.
  *
  * Returns: %TRUE if an object should be included in the filtered collection
diff --git a/gcr/gcr-fingerprint.c b/gcr/gcr-fingerprint.c
index 235cdf7..c2d314f 100644
--- a/gcr/gcr-fingerprint.c
+++ b/gcr/gcr-fingerprint.c
@@ -32,29 +32,19 @@
 #include <glib.h>
 
 /**
- * SECTION:gcr-fingerprint
- * @title: Key Fingerprints
- * @short_description: Fingerprints for public and private keys
- *
- * These functions generate key fingerprints for public keys, certificates and
- * key data. The fingerprints are created so that they they will be identical
- * for a key and its corresponding certificate.
- *
- * Note that in the case of certificates these are not fingerprints of the
- * actual certificate data, but rather of the public key contained in a
- * certificate.
- *
- * These fingerprints are created using the subjectPublicKeyInfo ASN.1 structure.
- */
-
-/**
  * gcr_fingerprint_from_subject_public_key_info:
  * @key_info: (array length=n_key_info): DER encoded subjectPublicKeyInfo structure
  * @n_key_info: length of DER encoded structure
  * @checksum_type: the type of fingerprint to create
  * @n_fingerprint: (out): the length of fingerprint returned
  *
- * Create a key fingerprint for a DER encoded subjectPublicKeyInfo.
+ * Create a key fingerprint for a DER encoded subjectPublicKeyInfo. The
+ * fingerprint is created so that it will be identical for a key and its
+ * corresponding certificate.
+ *
+ * Note that in the case of certificates this is not a fingerprint of the
+ * actual certificate data, but rather of the public key contained in a
+ * certificate.
  *
  * Returns: (transfer full) (nullable) (array length=n_fingerprint): the
  *          fingerprint or %NULL if the input was invalid.
diff --git a/gcr/gcr-import-interaction.c b/gcr/gcr-import-interaction.c
index 5fafa4c..b8da073 100644
--- a/gcr/gcr-import-interaction.c
+++ b/gcr/gcr-import-interaction.c
@@ -24,20 +24,12 @@
 #include "gcr-import-interaction.h"
 
 /**
- * SECTION:gcr-import-interaction
- * @title: GcrImportInteraction
- * @short_description: User interaction during importing
+ * GcrImportInteraction:
  *
  * This is an interface implemented by a caller performing an import. It allows
  * the importer to ask the caller for further information about the import.
  *
- * It must be implemented on a derived class of #GTlsInteraction
- */
-
-/**
- * GcrImportInteraction:
- *
- * Interface implemented by the caller performing an import.
+ * It must be implemented on a derived class of [class@Gio.TlsInteraction]
  */
 
 /**
@@ -48,7 +40,7 @@
  * @supplement_async: method which asynchronously supplements attributes before import
  * @supplement_finish: method which completes @supplement_async
  *
- * Interface implemented by implementations of #GcrImportInteraction.
+ * Interface implemented by implementations of [iface@ImportInteraction].
  */
 
 typedef GcrImportInteractionIface GcrImportInteractionInterface;
diff --git a/gcr/gcr-importer.c b/gcr/gcr-importer.c
index 0a119e8..802ded0 100644
--- a/gcr/gcr-importer.c
+++ b/gcr/gcr-importer.c
@@ -33,30 +33,23 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-importer
- * @title: GcrImporter
- * @short_description: Import certificates and keys
+ * GcrImporter:
  *
- * An interface which allows importing of certificates and keys. Each
- * #GcrImporter is registered with a set of PKCS\#11 attributes to match
- * stuff that it can import.
+ * An interface which allows importing of certificates and keys. Each importer
+ * is registered with a set of PKCS#11 attributes to match stuff that it can
+ * import.
  *
- * An importer gets passed a #GcrParser and accesses the currently parsed
+ * An importer gets passed a [class@Parser] and accesses the currently parsed
  * item. To create a set of importers that can import the currently parsed
- * item in a #GcrParser, use gcr_importer_create_for_parsed(). The list of
+ * item in a parser, use [func@Importer.create_for_parsed]. The list of
  * importers returned has the parsed item queued for import.
  *
- * To queue additional items with a importer use gcr_importer_queue_for_parsed().
- * In addition you can try and queue an additional item with a set of importers
- * using the gcr_importer_queue_and_filter_for_parsed().
- *
- * To start the import use gcr_importer_import() or the async variants.
- */
-
-/**
- * GcrImporter:
+ * To queue additional items with a importer use
+ * [method@Importer.queue_for_parsed].  In addition you can try and queue an
+ * additional item with a set of importers using the
+ * [func@Importer.queue_and_filter_for_parsed].
  *
- * Imports certificates and keys
+ * To start the import, use [method@Importer.import] or its async variants.
  */
 
 /**
@@ -64,9 +57,9 @@
  * @parent: parent interface
  * @create_for_parsed: implementation of gcr_importer_create_for_parsed(), required
  * @queue_for_parsed: implementation of gcr_importer_queue_for_parsed(), required
- * @import_sync: optional implemantionon of gcr_importer_import()
- * @import_async: implementation of gcr_importer_import_async(), required
- * @import_finish: implementation of gcr_importer_import_finish()
+ * @import_sync: optional implementation of [method@Importer.import]
+ * @import_async: implementation of [method@Importer.import_async], required
+ * @import_finish: implementation of [method@Importer.import_finish]
  *
  * Interface implemented for a #GcrImporter.
  */
@@ -282,7 +275,7 @@ gcr_importer_create_for_parsed (GcrParsed *parsed)
  * @parsed: a parsed item to import
  *
  * Queues an additional item to be imported. The parsed item is represented
- * by the state of the #GcrParser at the time of calling this method.
+ * by the state of the [class@Parser] at the time of calling this method.
  *
  * If the parsed item is incompatible with the importer, then this will
  * fail and the item will not be queued.
@@ -545,7 +538,7 @@ gcr_importer_set_interaction (GcrImporter *importer,
 /**
  * gcr_importer_register_well_known:
  *
- * Register built-in PKCS\#11 and GnuPG importers.
+ * Register built-in PKCS#11 and GnuPG importers.
  */
 void
 gcr_importer_register_well_known (void)
diff --git a/gcr/gcr-library.c b/gcr/gcr-library.c
index 399c7e2..44460ee 100644
--- a/gcr/gcr-library.c
+++ b/gcr/gcr-library.c
@@ -37,30 +37,19 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-library
- * @title: Library Utilities
- * @short_description: Library utilities such as version checks
- *
- * Basic library utilities such as version checks.
- */
-
-/**
  * GCR_CHECK_VERSION:
  * @major: the major version to check for
  * @minor: the minor version to check for
  * @micro: the micro version to check for
  *
- * Checks the version of the Gcr libarry that is being compiled
+ * Checks the version of the Gcr library that is being compiled
  * against.
  *
- * <example>
- * <title>Checking the version of the Gcr library</title>
- * <programlisting>
+ * ```
  * #if !GCR_CHECK_VERSION (3, 0, 0)
  * #warning Old Gcr version, disabling functionality
  * #endif
- * </programlisting>
- * </example>
+ * ```
  *
  * Returns: %TRUE if the version of the Gcr header files
  * is the same as or newer than the passed-in version.
@@ -84,35 +73,6 @@
  * The micro version number of the Gcr library.
  */
 
-/**
- * SECTION:gcr-pkcs11
- * @title: Library PKCS#11
- * @short_description: functions for manipulating GCR library global settings.
- *
- * Manage or lookup various global aspesct and settings of the library.
- *
- * The GCR library maintains a global list of PKCS\#11 modules to use for
- * its various lookups and storage operations. Each module is represented by
- * a GckModule object. You can examine this list by using
- * gcr_pkcs11_get_modules().
- *
- * The list is configured automatically by looking for system installed
- * PKCS\#11 modules. It's not not normally necessary to modify this list. But
- * if you have special needs, you can use the gcr_pkcs11_set_modules() and
- * gcr_pkcs11_add_module() to do so.
- *
- * Trust assertions are stored and looked up in specific PKCS\#11 slots.
- * You can examine this list with gcr_pkcs11_get_trust_lookup_slots()
- */
-
-/**
- * SECTION:gcr-private
- * @title: Private declarations
- * @short_description: private declarations to supress warnings.
- *
- * This section is only here to supress warnings, and should not be displayed.
- */
-
 G_LOCK_DEFINE_STATIC (modules);
 static GList *all_modules = NULL;
 static gboolean initialized_modules = FALSE;
@@ -272,7 +232,7 @@ on_initialize_registered (GObject *object,
  * @callback: callback which will be called when the operation completes
  * @user_data: data passed to the callback
  *
- * Asynchronously initialize the registered PKCS\#11 modules.
+ * Asynchronously initialize the registered PKCS#11 modules.
  */
 void
 gcr_pkcs11_initialize_async (GCancellable *cancellable,
@@ -304,7 +264,7 @@ gcr_pkcs11_initialize_async (GCancellable *cancellable,
  * @result: the asynchronous result
  * @error: location to place an error on failure
  *
- * Complete the asynchronous operation to initialize the registered PKCS\#11
+ * Complete the asynchronous operation to initialize the registered PKCS#11
  * modules.
  *
  * Returns: whether the operation was successful or not.
@@ -323,11 +283,10 @@ gcr_pkcs11_initialize_finish (GAsyncResult *result,
  * @cancellable: optional cancellable used to cancel the operation
  * @error: location to place an error on failure
  *
- * Asynchronously initialize the registered PKCS\#11 modules.
+ * Asynchronously initialize the registered PKCS#11 modules.
  *
  * Returns: whether the operation was successful or not.
  */
-
 gboolean
 gcr_pkcs11_initialize (GCancellable *cancellable,
                        GError **error)
@@ -366,11 +325,11 @@ gcr_pkcs11_initialize (GCancellable *cancellable,
 /**
  * gcr_pkcs11_get_modules:
  *
- * List all the PKCS\#11 modules that are used by the GCR library.
- * Each module is a #GckModule object.
+ * List all the PKCS#11 modules that are used by the GCR library.
+ * Each module is a [class@Gck.Module] object.
  *
- * An empty list of modules will be returned if gcr_pkcs11_set_modules(),
- * or gcr_pkcs11_initialize() has not yet run.
+ * An empty list of modules will be returned if [func@pkcs11_set_modules],
+ * or [func@pkcs11_initialize] has not yet run.
  *
  * When done with the list, free it with gck_list_unref_free().
  *
@@ -389,13 +348,13 @@ gcr_pkcs11_get_modules (void)
 
 /**
  * gcr_pkcs11_set_modules:
- * @modules: (element-type Gck.Module): a list of #GckModule
+ * @modules: (element-type Gck.Module): a list of PKCS#11 modules
  *
- * Set the list of PKCS\#11 modules that are used by the GCR library.
- * Each module in the list is a #GckModule object.
+ * Set the list of PKCS#11 modules that are used by the GCR library.
+ * Each module in the list is a [class@Gck.Module] object.
  *
  * It is not normally necessary to call this function. The available
- * PKCS\#11 modules installed on the system are automatically loaded
+ * PKCS#11 modules installed on the system are automatically loaded
  * by the GCR library.
  */
 void
@@ -416,11 +375,11 @@ gcr_pkcs11_set_modules (GList *modules)
  * gcr_pkcs11_add_module:
  * @module: a #GckModule
  *
- * Add a #GckModule to the list of PKCS\#11 modules that are used by the
+ * Add a #GckModule to the list of PKCS#11 modules that are used by the
  * GCR library.
  *
  * It is not normally necessary to call this function. The available
- * PKCS\#11 modules installed on the system are automatically loaded
+ * PKCS#11 modules installed on the system are automatically loaded
  * by the GCR library.
  */
 void
@@ -432,16 +391,16 @@ gcr_pkcs11_add_module (GckModule *module)
 
 /**
  * gcr_pkcs11_add_module_from_file:
- * @module_path: the full file path of the PKCS\#11 module
+ * @module_path: the full file path of the PKCS#11 module
  * @unused: unused
  * @error: a #GError or %NULL
  *
- * Initialize a PKCS\#11 module and add it to the modules that are
+ * Initialize a PKCS#11 module and add it to the modules that are
  * used by the GCR library. Note that is an error to initialize the same
- * PKCS\#11 module twice.
+ * PKCS#11 module twice.
  *
  * It is not normally necessary to call this function. The available
- * PKCS\#11 modules installed on the system are automatically loaded
+ * PKCS#11 modules installed on the system are automatically loaded
  * by the GCR library.
  *
  * Returns: whether the module was sucessfully added.
@@ -474,10 +433,10 @@ gcr_pkcs11_add_module_from_file (const gchar *module_path, gpointer unused,
 /**
  * gcr_pkcs11_get_trust_store_slot:
  *
- * Selects an appropriate PKCS\#11 slot to store trust assertions. The slot
+ * Selects an appropriate PKCS#11 slot to store trust assertions. The slot
  * to use is normally configured automatically by the system.
  *
- * This will only return a valid result after the gcr_pkcs11_initialize()
+ * This will only return a valid result after the [func@pkcs11_initialize]
  * method has been called.
  *
  * When done with the #GckSlot, use g_object_unref() to release it.
@@ -518,14 +477,12 @@ gcr_pkcs11_get_trust_store_slot (void)
 /**
  * gcr_pkcs11_get_trust_lookup_slots:
  *
- * List all the PKCS\#11 slots that are used by the GCR library for lookup
- * of trust assertions. Each slot is a #GckSlot object.
+ * List all the PKCS#11 slots that are used by the GCR library for lookup
+ * of trust assertions. Each slot is a [class@Gck.Slot] object.
  *
- * This will return an empty list if the gcr_pkcs11_initialize() function has
+ * This will return an empty list if the [func@pkcs11_initialize] function has
  * not yet been called.
  *
- * When done with the list, free it with gck_list_unref_free().
- *
  * Returns: (transfer full) (element-type Gck.Slot): a list of #GckSlot
  *          objects to use for lookup of trust, or the empty list if not
  *          initialized or no appropriate trust stores could be found.
@@ -564,7 +521,7 @@ gcr_pkcs11_get_trust_lookup_slots (void)
 /**
  * gcr_pkcs11_get_trust_store_uri:
  *
- * Get the PKCS\#11 URI that is used to identify which slot to use for
+ * Get the PKCS#11 URI that is used to identify which slot to use for
  * storing trust storage.
  *
  * Returns: (nullable): the uri which identifies trust storage slot
@@ -580,11 +537,11 @@ gcr_pkcs11_get_trust_store_uri (void)
  * gcr_pkcs11_set_trust_store_uri:
  * @pkcs11_uri: (nullable): the uri which identifies trust storage slot
  *
- * Set the PKCS\#11 URI that is used to identify which slot to use for
+ * Set the PKCS#11 URI that is used to identify which slot to use for
  * storing trust assertions.
  *
  * It is not normally necessary to call this function. The relevant
- * PKCS\#11 slot is automatically configured by the GCR library.
+ * PKCS#11 slot is automatically configured by the GCR library.
  */
 void
 gcr_pkcs11_set_trust_store_uri (const gchar *pkcs11_uri)
@@ -602,7 +559,7 @@ gcr_pkcs11_set_trust_store_uri (const gchar *pkcs11_uri)
 /**
  * gcr_pkcs11_get_trust_lookup_uris:
  *
- * Get the PKCS\#11 URIs that are used to identify which slots to use for
+ * Get the PKCS#11 URIs that are used to identify which slots to use for
  * lookup trust assertions.
  *
  * Returns: (nullable) (transfer none): the uri which identifies trust storage slot
@@ -618,11 +575,11 @@ gcr_pkcs11_get_trust_lookup_uris (void)
  * gcr_pkcs11_set_trust_lookup_uris:
  * @pkcs11_uris: (nullable): the uris which identifies trust lookup slots
  *
- * Set the PKCS\#11 URIs that are used to identify which slots to use for
+ * Set the PKCS#11 URIs that are used to identify which slots to use for
  * lookup of trust assertions.
  *
  * It is not normally necessary to call this function. The relevant
- * PKCS\#11 slots are automatically configured by the GCR library.
+ * PKCS#11 slots are automatically configured by the GCR library.
  */
 void
 gcr_pkcs11_set_trust_lookup_uris (const gchar **pkcs11_uris)
diff --git a/gcr/gcr-mock-prompter.c b/gcr/gcr-mock-prompter.c
index 60c5dc0..1ca4589 100644
--- a/gcr/gcr-mock-prompter.c
+++ b/gcr/gcr-mock-prompter.c
@@ -31,17 +31,15 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-mock-prompter
- * @title: GcrMockPrompter
- * @short_description: a mock GcrSystemPrompter for testing
+ * GcrMockPrompter:
  *
- * A mock GcrSystemPrompter used for testing against.
+ * A mock [class@SystemPrompter] used for testing against.
  *
- * Use gcr_mock_prompter_start() to start the mock prompter in another
+ * Use [func@MockPrompter.start] to start the mock prompter in another
  * thread. The returned string is the dbus address of the mock prompter.
- * You can pass this to gcr_system_prompt_open() as the prompter bus name.
+ * You can pass this to [func@SystemPrompt.open] as the prompter bus name.
  *
- * Use the gcr_mock_prompter_expect_confirm_ok() function and friends before
+ * Use the [func@MockPrompter.expect_confirm_ok] function and friends before
  * prompting to verify that the prompts are displayed as expected, and to
  * provide a response.
  */
diff --git a/gcr/gcr-parser.c b/gcr/gcr-parser.c
index 812ed94..ba3927e 100644
--- a/gcr/gcr-parser.c
+++ b/gcr/gcr-parser.c
@@ -45,28 +45,22 @@
 #include <gcrypt.h>
 
 /**
- * SECTION:gcr-parser
- * @title: GcrParser
- * @short_description: Parser for certificate and key files
+ * GcrParser:
  *
- * A #GcrParser can parse various certificate and key files such as OpenSSL
- * PEM files, DER encoded certifictes, PKCS\#8 keys and so on. Each various
- * format is identified by a value in the #GcrDataFormat enumeration.
+ * A parser for parsing various types of files or data.
  *
- * In order to parse data, a new parser is created with gcr_parser_new() and
- * then the #GcrParser::authenticate and #GcrParser::parsed signals should be
- * connected to. Data is then fed to the parser via gcr_parser_parse_data()
- * or gcr_parser_parse_stream().
+ * A `GcrParser` can parse various certificate and key files such as OpenSSL
+ * PEM files, DER encoded certifictes, PKCS#8 keys and so on. Each various
+ * format is identified by a value in the [enum@DataFormat] enumeration.
  *
- * During the #GcrParser::parsed signal the attributes that make up the currently
- * parsed item can be retrieved using the gcr_parser_get_parsed_attributes()
- * function.
- */
-
-/**
- * GcrParser:
+ * In order to parse data, a new parser is created with gcr_parser_new() and
+ * then the [signal@Parser::authenticate] and [signal@Parser::parsed] signals
+ * should be connected to. Data is then fed to the parser via
+ * [method@Parser.parse_data] or [method@Parser.parse_stream].
  *
- * A parser for parsing various types of files or data.
+ * During the [signal@Parser::parsed] signal the attributes that make up the
+ * currently parsed item can be retrieved using the
+ * [method@Parser.get_parsed_attributes] function.
  */
 
 /**
@@ -2192,12 +2186,12 @@ parse_openssh_public (GcrParser *self,
  * @GCR_FORMAT_DER_PRIVATE_KEY_EC: DER encoded EC private key
  * @GCR_FORMAT_DER_SUBJECT_PUBLIC_KEY: DER encoded SubjectPublicKeyInfo
  * @GCR_FORMAT_DER_CERTIFICATE_X509: DER encoded X.509 certificate
- * @GCR_FORMAT_DER_PKCS7: DER encoded PKCS\#7 container file which can contain certificates
- * @GCR_FORMAT_DER_PKCS8: DER encoded PKCS\#8 file which can contain a key
- * @GCR_FORMAT_DER_PKCS8_PLAIN: Unencrypted DER encoded PKCS\#8 file which can contain a key
- * @GCR_FORMAT_DER_PKCS8_ENCRYPTED: Encrypted DER encoded PKCS\#8 file which can contain a key
- * @GCR_FORMAT_DER_PKCS10: DER encoded PKCS\#10 certificate request file
- * @GCR_FORMAT_DER_PKCS12: DER encoded PKCS\#12 file which can contain certificates and/or keys
+ * @GCR_FORMAT_DER_PKCS7: DER encoded PKCS#7 container file which can contain certificates
+ * @GCR_FORMAT_DER_PKCS8: DER encoded PKCS#8 file which can contain a key
+ * @GCR_FORMAT_DER_PKCS8_PLAIN: Unencrypted DER encoded PKCS#8 file which can contain a key
+ * @GCR_FORMAT_DER_PKCS8_ENCRYPTED: Encrypted DER encoded PKCS#8 file which can contain a key
+ * @GCR_FORMAT_DER_PKCS10: DER encoded PKCS#10 certificate request file
+ * @GCR_FORMAT_DER_PKCS12: DER encoded PKCS#12 file which can contain certificates and/or keys
  * @GCR_FORMAT_OPENSSH_PUBLIC: OpenSSH v1 or v2 public key
  * @GCR_FORMAT_OPENPGP_PACKET: OpenPGP key packet(s)
  * @GCR_FORMAT_OPENPGP_ARMOR: OpenPGP public or private key armor encoded data
@@ -2207,11 +2201,11 @@ parse_openssh_public (GcrParser *self,
  * @GCR_FORMAT_PEM_PRIVATE_KEY_DSA: An OpenSSL style PEM file with a private DSA key
  * @GCR_FORMAT_PEM_PRIVATE_KEY_EC: An OpenSSL style PEM file with a private EC key
  * @GCR_FORMAT_PEM_CERTIFICATE_X509: An OpenSSL style PEM file with an X.509 certificate
- * @GCR_FORMAT_PEM_PKCS7: An OpenSSL style PEM file containing PKCS\#7
- * @GCR_FORMAT_PEM_PKCS8_PLAIN: Unencrypted OpenSSL style PEM file containing PKCS\#8
- * @GCR_FORMAT_PEM_PKCS8_ENCRYPTED: Encrypted OpenSSL style PEM file containing PKCS\#8
- * @GCR_FORMAT_PEM_PKCS10: An OpenSSL style PEM file containing PKCS\#10
- * @GCR_FORMAT_PEM_PKCS12: An OpenSSL style PEM file containing PKCS\#12
+ * @GCR_FORMAT_PEM_PKCS7: An OpenSSL style PEM file containing PKCS#7
+ * @GCR_FORMAT_PEM_PKCS8_PLAIN: Unencrypted OpenSSL style PEM file containing PKCS#8
+ * @GCR_FORMAT_PEM_PKCS8_ENCRYPTED: Encrypted OpenSSL style PEM file containing PKCS#8
+ * @GCR_FORMAT_PEM_PKCS10: An OpenSSL style PEM file containing PKCS#10
+ * @GCR_FORMAT_PEM_PKCS12: An OpenSSL style PEM file containing PKCS#12
  * @GCR_FORMAT_PEM_PUBLIC_KEY: An OpenSSL style PEM file containing a SubjectPublicKeyInfo
  * @GCR_FORMAT_DER_SPKAC: DER encoded SPKAC as generated by HTML5 keygen element
  * @GCR_FORMAT_BASE64_SPKAC: OpenSSL style SPKAC data
diff --git a/gcr/gcr-pkcs11-certificate.c b/gcr/gcr-pkcs11-certificate.c
index ea87961..e3c3b55 100644
--- a/gcr/gcr-pkcs11-certificate.c
+++ b/gcr/gcr-pkcs11-certificate.c
@@ -32,32 +32,18 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-pkcs11-certificate
- * @title: GcrPkcs11Certificate
- * @short_description: A certificate loaded from PKCS\#11 storage
+ * GcrPkcs11Certificate:
  *
- * A #GcrPkcs11Certificate is a certificate loaded from a PKCS\#11 storage.
- * It is also a valid #GckObject and can be used as such.
+ * A certificate loaded from a PKCS#11 storage.
+ * It is also a valid [class@Gck.Object] and can be used as such.
  *
  * Use gcr_pkcs11_certificate_lookup_issuer() to lookup the issuer of a given
- * certificate in the PKCS\#11 store.
+ * certificate in the PKCS#11 store.
  *
- * Various common PKCS\#11 certificate attributes are automatically loaded and
+ * Various common PKCS#11 certificate attributes are automatically loaded and
  * are available via gcr_pkcs11_certificate_get_attributes().
  */
 
-/**
- * GcrPkcs11Certificate:
- *
- * A certificate loaded from PKCS\#11 storage.
- */
-
-/**
- * GcrPkcs11CertificateClass:
- *
- * The class for #GcrPkcs11Certificate.
- */
-
 enum {
 	PROP_0,
 	PROP_ATTRIBUTES
@@ -330,7 +316,7 @@ gcr_pkcs11_certificate_get_attributes (GcrPkcs11Certificate *self)
  * @cancellable: a #GCancellable
  * @error: a #GError, or %NULL
  *
- * Lookup a the issuer of a @certificate in the PKCS\#11 storage. The
+ * Lookup a the issuer of a @certificate in the PKCS#11 storage. The
  * lookup is done using the issuer DN of the certificate. No certificate chain
  * verification is done. Use a crypto library to make trust decisions.
  *
@@ -370,7 +356,7 @@ gcr_pkcs11_certificate_lookup_issuer (GcrCertificate *certificate, GCancellable
  * @callback: a #GAsyncReadyCallback to call when the operation completes
  * @user_data: the data to pass to callback function
  *
- * Lookup a the issuer of a @certificate in the PKCS\#11 storage. The
+ * Lookup a the issuer of a @certificate in the PKCS#11 storage. The
  * lookup is done using the issuer DN of the certificate. No certificate chain
  * verification is done. Use a crypto library to make trust decisions.
  *
diff --git a/gcr/gcr-prompt.c b/gcr/gcr-prompt.c
index 403f796..3c8ed2a 100644
--- a/gcr/gcr-prompt.c
+++ b/gcr/gcr-prompt.c
@@ -26,33 +26,26 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-prompt
- * @title: GcrPrompt
- * @short_description: a user prompt
+ * GcrPrompt:
  *
- * A #GcrPrompt represents a prompt displayed to the user. It is an interface
- * with various implementations.
+ * A prompt displayed to the user. It is an interface with various
+ * implementations.
  *
  * Various properties are set on the prompt, and then the prompt is displayed
- * the various prompt methods like gcr_prompt_password_run().
+ * the various prompt methods like [method@Prompt.password_run].
  *
- * A #GcrPrompt may be used to display multiple related prompts. Most
- * implemantions do not hide the window between display of multiple related
+ * A `GcrPrompt` may be used to display multiple related prompts. Most
+ * implementions do not hide the window between display of multiple related
  * prompts, and the #GcrPrompt must be closed or destroyed in order to make
  * it go away. This allows the user to see that the prompts are related.
  *
- * Use #GcrPromptDialog to create an in-process GTK+ dialog prompt. Use
- * #GcrSystemPrompt to create a system prompt in a prompter process.
+ * Use `GcrPromptDialog` (part of gcr-ui) to create an in-process GTK+ dialog
+ * prompt. Use [class@SystemPrompt] to create a system prompt in a prompter
+ * process.
  *
- * The prompt implementation will always display the GcrPrompt:message property,
- * but may choose not to display the GcrPrompt:description or GcrPrompt:title
- * properties.
- */
-
-/**
- * GcrPrompt:
- *
- * Represents a #GcrPrompt displayed to the user.
+ * The prompt implementation will always display the [property@Prompt:message]
+ * property, but may choose not to display the [property@Prompt:description] or
+ * [property@Prompt:title] properties.
  */
 
 /**
@@ -64,7 +57,7 @@
  * @prompt_confirm_finish: complete a confirm prompt
  * @prompt_close: close a prompt
  *
- * The interface for implementing #GcrPrompt.
+ * The interface for implementing [class@Prompt].
  */
 
 /**
@@ -72,7 +65,7 @@
  * @GCR_PROMPT_REPLY_CONTINUE: the user replied with 'ok'
  * @GCR_PROMPT_REPLY_CANCEL: the prompt was cancelled
  *
- * Various replies returned by gcr_prompt_confirm() and friends.
+ * Various replies returned by [method@Prompt.confirm] and friends.
  */
 
 enum {
@@ -244,7 +237,7 @@ gcr_prompt_default_init (GcrPromptIface *iface)
 		 * handler has run, the prompt is closed. The various prompting methods
 		 * will return results as if the user dismissed the prompt.
 		 *
-		 * You can use the gcr_prompt_close() method to emit this signal.
+		 * You can use the [method@Prompt.close] method to emit this signal.
 		 */
 		signals[PROMPT_CLOSE] = g_signal_new ("prompt-close", GCR_TYPE_PROMPT, G_SIGNAL_RUN_FIRST,
 		                                      G_STRUCT_OFFSET (GcrPromptIface, prompt_close),
@@ -760,7 +753,7 @@ gcr_prompt_set_cancel_label (GcrPrompt *prompt,
 }
 
 /**
- * gcr_prompt_password_async:
+ * gcr_prompt_password_async: (virtual prompt_password_async)
  * @prompt: a prompt
  * @cancellable: optional cancellation object
  * @callback: called when the operation completes
@@ -789,7 +782,7 @@ gcr_prompt_password_async (GcrPrompt *prompt,
 }
 
 /**
- * gcr_prompt_password_finish:
+ * gcr_prompt_password_finish: (virtual prompt_password_finish)
  * @prompt: a prompt
  * @result: asynchronous result passed to callback
  * @error: location to place error on failure
@@ -913,7 +906,7 @@ gcr_prompt_password_run (GcrPrompt *prompt,
 }
 
 /**
- * gcr_prompt_confirm_async:
+ * gcr_prompt_confirm_async: (virtual prompt_confirm_async)
  * @prompt: a prompt
  * @cancellable: optional cancellation object
  * @callback: called when the operation completes
@@ -943,7 +936,7 @@ gcr_prompt_confirm_async (GcrPrompt *prompt,
 }
 
 /**
- * gcr_prompt_confirm_finish:
+ * gcr_prompt_confirm_finish: (virtual prompt_confirm_finish)
  * @prompt: a prompt
  * @result: asynchronous result passed to callback
  * @error: location to place error on failure
@@ -1026,7 +1019,7 @@ gcr_prompt_confirm (GcrPrompt *prompt,
  * represent the question correctly.
  *
  * This method will block until the a response is returned from the prompter
- * and will run a main loop similar to a gtk_dialog_run(). The application
+ * and will run a main loop similar to a `gtk_dialog_run()`. The application
  * will remain responsive but care must be taken to handle reentrancy issues.
  *
  * %GCR_PROMPT_REPLY_CONTINUE will be returned if the user confirms the prompt. The
@@ -1066,9 +1059,9 @@ gcr_prompt_confirm_run (GcrPrompt *prompt,
  * Closes the prompt so that in can no longer be used to prompt. The various
  * prompt methods will return results as if the user dismissed the prompt.
  *
- * The prompt may also be closed by the implementor of the #GcrPrompt object.
+ * The prompt may also be closed by the implementor of the prompt object.
  *
- * This emits the GcrPrompt::prompt-close signal on the prompt object.
+ * This emits the [signal@Prompt::prompt-close] signal on the prompt object.
  */
 void
 gcr_prompt_close (GcrPrompt *prompt)
diff --git a/gcr/gcr-secret-exchange.c b/gcr/gcr-secret-exchange.c
index 8140d50..cadca83 100644
--- a/gcr/gcr-secret-exchange.c
+++ b/gcr/gcr-secret-exchange.c
@@ -33,43 +33,30 @@
 EGG_SECURE_DECLARE (secret_exchange);
 
 /**
- * SECTION:gcr-secret-exchange
- * @title: GcrSecretExchange
- * @short_description: Exchange secrets between processes in an unexposed way.
+ * GcrSecretExchange:
  *
  * Allows exchange of secrets between two processes on the same system without
  * exposing those secrets to things like loggers, non-pageable memory etc.
  *
  * This does not protect against active attacks like MITM attacks.
  *
- * Each side creates a #GcrSecretExchange object, and one of the sides calls
- * gcr_secret_exchange_begin(). This creates a string, which should be passed
+ * Each side creates a secret exchange object, and one of the sides calls
+ * [method@SecretExchange.begin]. This creates a string, which should be passed
  * to the other side. Each side passes the strings it receives into
- * gcr_secret_exchange_receive().
+ * [method@SecretExchange.receive].
  *
  * In order to send a reply (either with or without a secret) use
- * gcr_secret_exchange_send(). A side must have had gcr_secret_exchange_receive()
- * successfully called before it can use gcr_secret_exchange_send().
+ * [method@SecretExchange.send]. A side must have successfully called
+ * [method@SecretExchange.receive] before it can use
+ * [method@SecretExchange.send].
  *
- * The #GcrSecretExchange objects can be used for multiple iterations of the
+ * The secret exchange objects can be used for multiple iterations of the
  * conversation, or for just one request/reply. The only limitation being that
  * the initial request cannot contain a secret.
  *
  * Caveat: Information about the approximate length (rounded up to the nearest
  * 16 bytes) may be leaked. If this is considered inacceptable, do not use
- * #GcrSecretExchange.
- */
-
-/**
- * GcrSecretExchange:
- *
- * An object representing one side of a secret exchange.
- */
-
-/**
- * GcrSecretExchangeClass:
- *
- * The class for #GcrSecretExchange
+ * [class@SecretExchange].
  */
 
 /**
@@ -224,7 +211,7 @@ gcr_secret_exchange_finalize (GObject *obj)
  *
  * Specify a protocol of %NULL to allow any protocol. This is especially
  * relevant on the side of the exchange that does not call
- * gcr_secret_exchange_begin(), that is the originator. Currently the only
+ * [method@SecretExchange.begin], that is the originator. Currently the only
  * protocol supported is %GCR_SECRET_EXCHANGE_PROTOCOL_1.
  *
  * Returns: (transfer full): A new #GcrSecretExchange object
@@ -243,8 +230,8 @@ gcr_secret_exchange_new (const gchar *protocol)
  * Get the secret exchange protocol.
  *
  * Will return %NULL if no protocol was specified, and either
- * gcr_secret_exchange_begin() or gcr_secret_exchange_receive() have not been
- * called successfully.
+ * [method@SecretExchange.begin] or [method@SecretExchange.receive] have not
+ * been called successfully.
  *
  * Returns: the protocol or %NULL
  */
@@ -262,7 +249,7 @@ gcr_secret_exchange_get_protocol (GcrSecretExchange *self)
  * @self: a #GcrSecretExchange object
  *
  * Begin the secret exchange. The resulting string should be sent to the other
- * side of the exchange. The other side should use gcr_secret_exchange_receive()
+ * side of the exchange. The other side should use [method@SecretExchange.receive]
  * to process the string.
  *
  * Returns: (transfer full): A newly allocated string to be sent to the other
@@ -387,7 +374,8 @@ perform_decrypt (GcrSecretExchange *self,
  * @exchange: the string received
  *
  * Receive a string from the other side of secret exchange. This string will
- * have been created by gcr_secret_exchange_begin() or gcr_secret_exchange_send().
+ * have been created by [method@SecretExchange.begin] or
+ * [method@SecretExchange.send].
  *
  * After this call completes successfully the value returned from
  * gcr_secret_exchange_get_secret() will have changed.
@@ -514,7 +502,7 @@ perform_encrypt (GcrSecretExchange *self,
  * Send a reply to the other side of the secret exchange, optionally sending a
  * secret.
  *
- * gcr_secret_exchange_receive() must have been successfully called at least
+ * [method@SecretExchange.receive] must have been successfully called at least
  * once on this object. In other words this object must have received data
  * from the other side of the secret exchange, before we can send a secret.
  *
@@ -864,7 +852,7 @@ gcr_secret_exchange_class_init (GcrSecretExchangeClass *klass)
 	 * The protocol being used for the exchange.
 	 *
 	 * Will be %NULL if no protocol was specified when creating this object,
-	 * and either gcr_secret_exchange_begin() or gcr_secret_exchange_receive()
+	 * and either [method@SecretExchange.begin] or [method@SecretExchange.receive]
 	 * have not been called successfully.
 	 */
 	g_object_class_install_property (gobject_class, PROP_PROTOCOL,
diff --git a/gcr/gcr-secure-memory.c b/gcr/gcr-secure-memory.c
index 201861a..1ff94e0 100644
--- a/gcr/gcr-secure-memory.c
+++ b/gcr/gcr-secure-memory.c
@@ -32,22 +32,6 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-secure-memory
- * @title: Non-pageable Memory
- * @short_description: Secure non-pageable memory
- *
- * Normal allocated memory can be paged to disk at the whim of the operating
- * system. This can be a problem for sensitive information like passwords, keys
- * and secrets.
- *
- * The Gcr library holds passwords and keys in non-pageable, or locked memory.
- * This is only possible if the OS contains support for it.
- *
- * These functions allow applications to use secure memory to hold passwords
- * and other sensitive information.
- */
-
-/**
  * gcr_secure_memory_new: (skip)
  * @type: C type of the objects to allocate
  * @n_objects: number of objects to allocate
diff --git a/gcr/gcr-simple-certificate.c b/gcr/gcr-simple-certificate.c
index 3daba64..0331a3b 100644
--- a/gcr/gcr-simple-certificate.c
+++ b/gcr/gcr-simple-certificate.c
@@ -27,29 +27,13 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-simple-certificate
- * @title: GcrSimpleCertificate
- * @short_description: A certificate loaded from a memory buffer
- *
- * An implementation of #GcrCertificate which loads a certificate from DER
- * data already located in memory.
- *
- * To create a #GcrSimpleCertificate object use the
- * gcr_simple_certificate_new() or gcr_simple_certificate_new_static()
- * functions.
- */
-
-/**
  * GcrSimpleCertificate:
  *
- * A #GcrCertificate which represents a certificate already in memory.
- */
-
-/**
- * GcrSimpleCertificateClass:
- * @parent_class: The parent class
+ * An implementation of [iface@Certificate] which loads a certificate from DER
+ * data already located in memory.
  *
- * The class for #GcrSimpleCertificate.
+ * To create an object, use the [ctor@SimpleCertificate.new] or
+ * [ctor@SimpleCertificate.new_static] functions.
  */
 
 struct _GcrSimpleCertificatePrivate {
diff --git a/gcr/gcr-simple-collection.c b/gcr/gcr-simple-collection.c
index c90149b..d0c5a30 100644
--- a/gcr/gcr-simple-collection.c
+++ b/gcr/gcr-simple-collection.c
@@ -27,26 +27,13 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-simple-collection
- * @title: GcrSimpleCollection
- * @short_description: A simple implementation of GcrCollection
- *
- * A simple implementation of #GcrCollection, which you can add and remove
- * objects from. Use gcr_simple_collection_add() to do this
- * gcr_simple_collection_remove().
- */
-
-/**
  * GcrSimpleCollection:
  *
- * A simple implementation of #GcrCollection.
- */
-
-/**
- * GcrSimpleCollectionClass:
- * @parent_class: The parent class
+ * A simple implementation of [iface@Collection], which you can add and remove
+ * objects from.
  *
- * The class for #GcrSimpleCollection.
+ * You can use [method@SimpleCollection.add] to add objects, and
+ * [method@SimpleCollection.remove] to remove them again.
  */
 
 struct _GcrSimpleCollectionPrivate {
diff --git a/gcr/gcr-ssh-askpass.c b/gcr/gcr-ssh-askpass.c
index fd9e20b..1a18589 100644
--- a/gcr/gcr-ssh-askpass.c
+++ b/gcr/gcr-ssh-askpass.c
@@ -35,26 +35,12 @@
 const char *gcr_ssh_askpass_executable = LIBEXECDIR "/gcr-ssh-askpass";
 
 /**
- * SECTION:gcr-ssh-askpass
- * @title: GcrSshAskpass
- * @short_description: Allows an ssh command to callback for a password
+ * GcrSshAskpass:
  *
  * When used as the setup function while spawning an ssh command like ssh-add
  * or ssh, this allows callbacks for passwords on the provided interaction.
  */
 
-/**
- * GcrSshAskpass:
- *
- * An object containing the password prompting state.
- */
-
-/**
- * GcrSshAskpassClass:
- *
- * The class for #GcrSshAskpass
- */
-
 enum {
 	PROP_0,
 	PROP_INTERACTION
diff --git a/gcr/gcr-system-prompt.c b/gcr/gcr-system-prompt.c
index 530faf6..ceba221 100644
--- a/gcr/gcr-system-prompt.c
+++ b/gcr/gcr-system-prompt.c
@@ -35,35 +35,19 @@
 #include <glib/gi18n.h>
 
 /**
- * SECTION:gcr-system-prompt
- * @title: GcrSystemPrompt
- * @short_description: a system modal prompt
+ * GcrSystemPrompt:
  *
- * A #GcrPrompt implementation which calls to the system prompter to
+ * A [iface@Prompt] implementation which calls to the system prompter to
  * display prompts in a system modal fashion.
  *
  * Since the system prompter usually only displays one prompt at a time, you
- * may have to wait for the prompt to be displayed. Use gcr_system_prompt_open()
+ * may have to wait for the prompt to be displayed. Use [func@SystemPrompt.open]
  * or a related function to open a prompt. Since this can take a long time, you
  * should always check that the prompt is still needed after it is opened. A
  * previous prompt may have already provided the information needed and you
  * may no longer need to prompt.
  *
- * Use gcr_system_prompt_close() to close the prompt when you're done with it.
- */
-
-/**
- * GcrSystemPrompt:
- *
- * A #GcrPrompt which shows a system prompt. This is usually a system modal
- * dialog.
- */
-
-/**
- * GcrSystemPromptClass:
- * @parent_class: parent class
- *
- * The class for #GcrSystemPrompt.
+ * Use [method@SystemPrompt.close] to close the prompt when you're done with it.
  */
 
 /**
@@ -603,7 +587,7 @@ gcr_system_prompt_class_init (GcrSystemPromptClass *klass)
  * gcr_system_prompt_get_secret_exchange:
  * @self: a prompter
  *
- * Get the current #GcrSecretExchange used to transfer secrets in this prompt.
+ * Get the current [class@SecretExchange] used to transfer secrets in this prompt.
  *
  * Returns: (transfer none): the secret exchange
  */
@@ -1379,9 +1363,9 @@ gcr_system_prompt_open_async (gint timeout_seconds,
 
 /**
  * gcr_system_prompt_open_for_prompter_async:
- * @prompter_name: (nullable): the prompter dbus name
+ * @prompter_name: (nullable): the prompter D-Bus name
  * @timeout_seconds: the number of seconds to wait to access the prompt, or -1
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass the callback
  *
@@ -1456,7 +1440,7 @@ gcr_system_prompt_open_finish (GAsyncResult *result,
 /**
  * gcr_system_prompt_open:
  * @timeout_seconds: the number of seconds to wait to access the prompt, or -1
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error on failure
  *
  * Opens a system prompt with the default prompter.
diff --git a/gcr/gcr-system-prompter.c b/gcr/gcr-system-prompter.c
index 10948cf..dbb51b0 100644
--- a/gcr/gcr-system-prompter.c
+++ b/gcr/gcr-system-prompter.c
@@ -38,23 +38,18 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-system-prompter
- * @title: GcrSystemPrompter
- * @short_description: a prompter which displays system prompts
+ * GcrSystemPrompter:
+ *
+ * A prompter used by implementations of system prompts.
  *
- * This is a DBus service which is rarely implemented. Use #GcrSystemPrompt
+ * This is a D-Bus service which is rarely implemented. Use [class@SystemPrompt]
  * to display system prompts.
  *
- * The GcrSystemPrompter service responds to dbus requests to create system
+ * The system prompter service responds to D-Bus requests to create system
  * prompts and creates #GcrPrompt type objects to display those prompts.
  *
- * Pass the GType of the implementation of #GcrPrompt to gcr_system_prompter_new().
- */
-
-/**
- * GcrSystemPrompter:
- *
- * A prompter used by implementations of system prompts.
+ * Pass the GType of the implementation of [iface@Prompt] to
+ * [ctor@SystemPrompter.new].
  */
 
 /**
diff --git a/gcr/gcr-trust.c b/gcr/gcr-trust.c
index af41d02..786ab4f 100644
--- a/gcr/gcr-trust.c
+++ b/gcr/gcr-trust.c
@@ -34,40 +34,6 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-trust
- * @title: Trust Storage and Lookups
- * @short_description: Store and lookup bits of information used for
- * verifying certificates.
- *
- * These functions provide access to stored information about which
- * certificates the system and user trusts as certificate authority trust
- * anchors, or overrides to the normal verification of certificates.
- *
- * Trust anchors are used to verify the certificate authority in a certificate
- * chain. Trust anchors are always valid for a given purpose. The most common
- * purpose is the #GCR_PURPOSE_SERVER_AUTH and is used for a client application
- * to verify that the certificate at the server side of a TLS connection is
- * authorized to act as such. To check if a certificate is a trust anchor use
- * gcr_trust_is_certificate_anchored().
- *
- * Pinned certificates are used when a user overrides the default trust
- * decision for a given certificate. They're often used with self-signed
- * certificates. Pinned certificates are always only valid for a single peer
- * such as the remote host with which TLS is being performed. To lookup
- * pinned certificates use gcr_trust_is_certificate_pinned().
- *
- * After the user has requested to override the trust decision
- * about a given certificate then a pinned certificates can be added by using
- * the gcr_trust_add_pinned_certificate() function.
- *
- * These functions do not constitute a viable method for verifying certificates
- * used in TLS or other locations. Instead they support such verification
- * by providing some of the needed data for a trust decision.
- *
- * The storage is provided by pluggable PKCS\#11 modules.
- */
-
-/**
  * GCR_PURPOSE_SERVER_AUTH:
  *
  * The purpose used to verify the server certificate in a TLS connection. This
@@ -225,7 +191,7 @@ thread_is_certificate_pinned (GTask *task, gpointer object,
  * pinned certificate overrides all other certificate verification.
  *
  * When the operation is finished, callback will be called. You can then call
- * gcr_trust_is_certificate_pinned_finish() to get the result of the
+ * [func@Gcr.trust_is_certificate_pinned_finish] to get the result of the
  * operation.
  */
 void
@@ -435,7 +401,7 @@ thread_add_pinned_certificate (GTask *task, gpointer object,
  * does not add another, and succeeds without error.
  *
  * When the operation is finished, callback will be called. You can then call
- * gcr_trust_add_pinned_certificate_finish() to get the result of the
+ * [func@Gcr.trust_add_pinned_certificate_finish] to get the result of the
  * operation.
  */
 void
@@ -714,8 +680,8 @@ perform_is_certificate_anchored (GckAttributes *attrs,
  * anchor is used to verify the signatures on other certificates when verifying
  * a certificate chain. Also known as a trusted certificate authority.
  *
- * This call may block, see gcr_trust_is_certificate_anchored_async() for the
- * non-blocking version.
+ * This call may block, see [func@Gcr.trust_is_certificate_anchored_async] for
+ * the non-blocking version.
  *
  * In the case of an error, %FALSE is also returned. Check @error to detect
  * if an error occurred.
diff --git a/gcr/gcr-union-collection.c b/gcr/gcr-union-collection.c
index b66b7c8..846b226 100644
--- a/gcr/gcr-union-collection.c
+++ b/gcr/gcr-union-collection.c
@@ -28,26 +28,11 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-union-collection
- * @title: GcrUnionCollection
- * @short_description: A GcrCollection which combines other collections
- *
- * An implementation of #GcrCollection, which combines the objects in
- * other #GcrCollections. Use gcr_union_collection_add() to add and
- * gcr_union_collection_remove() to remove them.
- */
-
-/**
  * GcrUnionCollection:
  *
- * A union implementation of #GcrCollection.
- */
-
-/**
- * GcrUnionCollectionClass:
- * @parent_class: The parent class
- *
- * The class for #GcrUnionCollection.
+ * An implementation of #GcrCollection, which combines the objects in
+ * other [iface@Collection]s. Use [method@UnionCollection.add] to add and
+ * [method@UnionCollection.remove] to remove them.
  */
 
 struct _GcrUnionCollectionPrivate {