[gcr/gi-docsgen: 9/9] docs: Port from gtk-doc to gi-docgen




commit 446ded32df8db56e41ed345dfaea67b5154facf9
Author: Niels De Graef <nielsdegraef gmail com>
Date:   Thu Sep 30 13:41:44 2021 +0200

    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

 docs/{reference => }/COPYING                       |   0
 docs/gck/gck.toml.in                               |  34 +
 docs/gck/meson.build                               |  32 +
 docs/gck/pkcs11-links.md                           |  32 +
 docs/gcr/gcr-base.toml.in                          |  40 +
 docs/gcr/meson.build                               |  35 +
 docs/gcr/non-pageable-memory.md                    |  21 +
 docs/gcr/pkcs11-configuration.md                   |  16 +
 docs/gcr/trust-store.md                            |  38 +
 docs/meson.build                                   |  14 +-
 docs/reference/gck/gck-docs.sgml                   |  37 -
 docs/reference/gck/gck-overrides.txt               |   2 -
 docs/reference/gck/gck-pkcs11-links.xml            |  25 -
 docs/reference/gck/gck-sections.txt                | 484 -----------
 docs/reference/gck/gck.types                       |  15 -
 docs/reference/gck/meson.build                     |  36 -
 docs/reference/gck/version.xml.in                  |   1 -
 docs/reference/gcr/gcr-docs.sgml                   |  81 --
 docs/reference/gcr/gcr-overrides.txt               |   2 -
 docs/reference/gcr/gcr-sections.txt                | 899 ---------------------
 docs/reference/gcr/gcr-shooter.c                   | 466 -----------
 docs/reference/gcr/gcr-shooter.h                   |  23 -
 docs/reference/gcr/gcr-visual-index.xml            |  27 -
 docs/reference/gcr/gcr-widgets.c                   | 236 ------
 docs/reference/gcr/gcr.types                       |  29 -
 docs/reference/gcr/meson.build                     |  83 --
 docs/reference/gcr/version.xml.in                  |   1 -
 docs/ui/gcr-ui.toml.in                             |  56 ++
 .../gcr => ui}/images/certificate-widget.png       | Bin
 .../gcr => ui}/images/combo-selector.png           | Bin
 .../{reference/gcr => ui}/images/import-button.png | Bin
 docs/{reference/gcr => ui}/images/key-widget.png   | Bin
 .../{reference/gcr => ui}/images/list-selector.png | Bin
 .../{reference/gcr => ui}/images/tree-selector.png | Bin
 .../{reference/gcr => ui}/images/viewer-widget.png | Bin
 docs/ui/meson.build                                |  33 +
 docs/ui/widget-gallery.md                          |  20 +
 gck/gck-attributes.c                               | 294 ++++---
 gck/gck-enumerator.c                               |  20 +-
 gck/gck-misc.c                                     |  73 +-
 gck/gck-module.c                                   |  55 +-
 gck/gck-modules.c                                  |  16 +-
 gck/gck-object-cache.c                             |  25 +-
 gck/gck-object.c                                   |  73 +-
 gck/gck-password.c                                 |  32 +-
 gck/gck-session.c                                  | 122 ++-
 gck/gck-slot.c                                     |  33 +-
 gck/gck-uri.c                                      |  44 +-
 gcr/gcr-certificate-chain.c                        |  35 +-
 gcr/gcr-certificate-request.c                      |  46 +-
 gcr/gcr-certificate.c                              |  21 +-
 gcr/gcr-collection.c                               |  19 +-
 gcr/gcr-column.c                                   |  20 +-
 gcr/gcr-comparable.c                               |  13 +-
 gcr/gcr-filter-collection.c                        |  20 +-
 gcr/gcr-fingerprint.c                              |  24 +-
 gcr/gcr-import-interaction.c                       |  14 +-
 gcr/gcr-importer.c                                 |  39 +-
 gcr/gcr-library.c                                  | 105 +--
 gcr/gcr-mock-prompter.c                            |  12 +-
 gcr/gcr-parser.c                                   |  52 +-
 gcr/gcr-pkcs11-certificate.c                       |  28 +-
 gcr/gcr-prompt.c                                   |  51 +-
 gcr/gcr-secret-exchange.c                          |  46 +-
 gcr/gcr-secure-memory.c                            |  16 -
 gcr/gcr-simple-certificate.c                       |  24 +-
 gcr/gcr-simple-collection.c                        |  21 +-
 gcr/gcr-ssh-askpass.c                              |  16 +-
 gcr/gcr-system-prompt.c                            |  32 +-
 gcr/gcr-system-prompter.c                          |  19 +-
 gcr/gcr-trust.c                                    |  42 +-
 gcr/gcr-union-collection.c                         |  21 +-
 meson.build                                        |   6 +-
 ui/gcr-certificate-renderer.c                      |   6 +-
 ui/gcr-certificate-request-renderer.c              |   8 +-
 ui/gcr-certificate-widget.c                        |  34 +-
 ui/gcr-collection-model.c                          |  37 +-
 ui/gcr-combo-selector.c                            |  22 +-
 ui/gcr-failure-renderer.c                          |   6 +
 ui/gcr-import-button.c                             |  18 +-
 ui/gcr-key-renderer.c                              |   2 +-
 ui/gcr-key-widget.c                                |  32 +-
 ui/gcr-list-selector.c                             |  17 +-
 ui/gcr-prompt-dialog.c                             |  21 +-
 ui/gcr-renderer.c                                  |  23 +-
 ui/gcr-secure-entry-buffer.c                       |  34 +-
 ui/gcr-tree-selector.c                             |  18 +-
 ui/gcr-unlock-options-widget.c                     |  25 +-
 ui/gcr-viewer-widget.c                             |  19 +-
 ui/gcr-viewer.c                                    |  29 +-
 90 files changed, 1032 insertions(+), 3666 deletions(-)
---
diff --git a/docs/reference/COPYING b/docs/COPYING
similarity index 100%
rename from docs/reference/COPYING
rename to docs/COPYING
diff --git a/docs/gck/gck.toml.in b/docs/gck/gck.toml.in
new file mode 100644
index 0000000..696b940
--- /dev/null
+++ b/docs/gck/gck.toml.in
@@ -0,0 +1,34 @@
+[library]
+namespace = "Gck"
+version = "@GCK_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gcr/";
+repository_url = "https://gitlab.gnome.org/GNOME/gcr.git";
+authors = "GCK contributors"
+license = "LGPL-2.0-or-later"
+description = "GObject bindings for PKCS#11"
+dependencies = [ "GObject-2.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable";
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "GObject interfaces and objects"
+  docs_url = "https://developer.gnome.org/gio/stable";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gcr/-/blob/master/";
+
+[extra]
+content_files = [
+  'pkcs11-links.md',
+]
diff --git a/docs/gck/meson.build b/docs/gck/meson.build
new file mode 100644
index 0000000..a7491d0
--- /dev/null
+++ b/docs/gck/meson.build
@@ -0,0 +1,32 @@
+gck_content_files = [
+  'pkcs11-links.md',
+]
+
+gck_toml = configure_file(
+  input: 'gck.toml.in',
+  output: 'gck.toml',
+  configuration: {
+    'GCK_VERSION': gck_major_version,
+  },
+)
+
+gck_docs = custom_target('gck-docs',
+  input: gck_gir[0],
+  output: 'gck-@0@'.format(gck_major_version),
+  command: [
+    gi_docgen,
+    'generate',
+    '--quiet',
+    '--fatal-warnings',
+    '--add-include-path=@0@'.format(source_root / 'gck'),
+    '--config', gck_toml,
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT@',
+  ],
+  depend_files: [ gck_toml, gck_content_files ],
+  build_by_default: true,
+  install: true,
+  install_dir: get_option('datadir') / 'doc',
+)
diff --git a/docs/gck/pkcs11-links.md b/docs/gck/pkcs11-links.md
new file mode 100644
index 0000000..ad89d6c
--- /dev/null
+++ b/docs/gck/pkcs11-links.md
@@ -0,0 +1,32 @@
+Title: About PKCS#11
+
+About PKCS#11
+=============
+PKCS#11 is an API for storing and using crypto objects, and performing crypto
+operations on them.
+
+It is specified at the [RSA website] and a [handy PKCS#11 reference] is also
+available.
+
+## PKCS#11 URIs
+[PKCS#11 URIs] are a standard for referring to PKCS#11 modules, tokens, or
+objects. What the PKCS#11 URI refers to depends on the context in which it is
+used.
+
+A PKCS#11 URI can always resolve to more than one object, token or module. A
+PKCS#11 URI that refers to a token, would (when used in a context that expects
+objects) refer to all the token on that module.
+
+To parse a PKCS#11 URI, use the [func@uri_parse] function passing in the type of
+context in which you're using the URI. To build a URI, use the [func@uri_build]
+function.
+
+In most cases, the parsing or building of URIs is already handled for you in the
+GCK library. For example: to enumerate objects that match a PKCS#11 URI use the
+[func@modules_enumerate_uri] function.
+
+
+
+[RSA website]: http://www.rsa.com/rsalabs/node.asp?id=2133
+[handy PKCS#11 reference]: http://www.cryptsoft.com/pkcs11doc/
+[PKCS#11 URIs]: http://tools.ietf.org/html/draft-pechanec-pkcs11uri-03
diff --git a/docs/gcr/gcr-base.toml.in b/docs/gcr/gcr-base.toml.in
new file mode 100644
index 0000000..3c746a0
--- /dev/null
+++ b/docs/gcr/gcr-base.toml.in
@@ -0,0 +1,40 @@
+[library]
+namespace = "Gcr"
+version = "@GCR_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gcr/";
+repository_url = "https://gitlab.gnome.org/GNOME/gcr.git";
+authors = "GCR contributors"
+license = "LGPL-2.0-or-later"
+description = "GObject and GUI library for high level crypto handling"
+dependencies = [ "GObject-2.0", "Gio-2.0", "Gck-@GCK_VERSION@" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable";
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "GObject interfaces and objects"
+  docs_url = "https://developer.gnome.org/gio/stable";
+
+  [dependencies."Gck-@GCK_VERSION@"]
+  name = "Gck"
+  description = "GObject bindings for PKCS#11"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gcr/-/blob/master/";
+
+[extra]
+content_files = [
+  'non-pageable-memory.md',
+  'pkcs11-configuration.md',
+  'trust-store.md',
+]
diff --git a/docs/gcr/meson.build b/docs/gcr/meson.build
new file mode 100644
index 0000000..ed2c2c8
--- /dev/null
+++ b/docs/gcr/meson.build
@@ -0,0 +1,35 @@
+gcr_base_content_files = [
+  'non-pageable-memory.md',
+  'pkcs11-configuration.md',
+  'trust-store.md',
+]
+
+gcr_base_toml = configure_file(
+  input: 'gcr-base.toml.in',
+  output: '@BASENAME@',
+  configuration: {
+    'GCR_VERSION': gcr_major_version,
+    'GCK_VERSION': gck_major_version,
+  },
+)
+
+gcr_base_docs = custom_target('gcr-docs',
+  input: gcr_gir[0],
+  output: 'gcr-@0@'.format(gcr_major_version),
+  command: [
+    gi_docgen,
+    'generate',
+    '--quiet',
+    '--fatal-warnings',
+    '--add-include-path=@0@'.format(source_root / 'gcr'),
+    '--config', gcr_base_toml,
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT@',
+  ],
+  depend_files: [ gcr_base_toml, gcr_base_content_files ],
+  build_by_default: true,
+  install: true,
+  install_dir: get_option('datadir') / 'doc',
+)
diff --git a/docs/gcr/non-pageable-memory.md b/docs/gcr/non-pageable-memory.md
new file mode 100644
index 0000000..1f77f42
--- /dev/null
+++ b/docs/gcr/non-pageable-memory.md
@@ -0,0 +1,21 @@
+Title: Non-pageable memory
+
+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.
+
+The set of `gcr_secure_memory_*()` functions allow applications to use secure
+memory to hold passwords and other sensitive information.
+
+* [func@Gcr.secure_memory_alloc]
+* [func@Gcr.secure_memory_try_alloc]
+* [func@Gcr.secure_memory_realloc]
+* [func@Gcr.secure_memory_try_realloc]
+* [func@Gcr.secure_memory_is_secure]
+* [func@Gcr.secure_memory_strdup]
+* [func@Gcr.secure_memory_strfree]
diff --git a/docs/gcr/pkcs11-configuration.md b/docs/gcr/pkcs11-configuration.md
new file mode 100644
index 0000000..8c06f05
--- /dev/null
+++ b/docs/gcr/pkcs11-configuration.md
@@ -0,0 +1,16 @@
+Title: PKCS#11 configuration
+
+PKCS#11 configuration
+=====================
+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 [class@Gck.Module] object. You can examine this list by using
+[func@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 [func@pkcs11_set_modules] and
+[func@pkcs11_add_module] (or [func@pkcs11_add_module_from_file]) to do so.
+
+Trust assertions are stored and looked up in specific PKCS#11 slots.
+You can examine this list with [func@pkcs11_get_trust_lookup_slots].
diff --git a/docs/gcr/trust-store.md b/docs/gcr/trust-store.md
new file mode 100644
index 0000000..1c97ec2
--- /dev/null
+++ b/docs/gcr/trust-store.md
@@ -0,0 +1,38 @@
+Title: Trust store
+Description: Store/Lookup bits of information used for verifying certificates.
+
+Trust store
+===========
+GCR provides functions to access information about which certificates the system
+and user trusts, such as certificate authority trust anchors, or overrides
+to the normal verification of certificates.
+
+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.
+
+Trust Anchors
+-------------
+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 [const@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
+[func@Gcr.trust_is_certificate_anchored], or
+[func@Gcr.trust_is_certificate_anchored_async] for the asynchronous version
+
+Pinned certificates
+-------------------
+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
+[func@Gcr.trust_is_certificate_pinned], or
+[func@Gcr.trust_is_certificate_pinned_async] for the asynchronous version.
+
+After the user has requested to override the trust decision about a given
+certificate then a pinned certificates can be added by using the
+[func@Gcr.trust_add_pinned_certificate] function, or
+[func@Gcr.trust_add_pinned_certificate_async] for the asynchronous version.
diff --git a/docs/meson.build b/docs/meson.build
index f353516..b90095c 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,2 +1,12 @@
-subdir('reference/gck')
-subdir('reference/gcr')
+gi_docgen = find_program('gi-docgen')
+
+subdir('gck')
+subdir('gcr')
+subdir('ui')
+
+# Create a pseudo target that build all docs at once
+alias_target('docs',
+  gck_docs,
+  gcr_base_docs,
+  gcr_ui_docs,
+)
diff --git a/docs/ui/gcr-ui.toml.in b/docs/ui/gcr-ui.toml.in
new file mode 100644
index 0000000..4ccf466
--- /dev/null
+++ b/docs/ui/gcr-ui.toml.in
@@ -0,0 +1,56 @@
+[library]
+namespace = "GcrUi"
+version = "@GCR_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gcr/";
+repository_url = "https://gitlab.gnome.org/GNOME/gcr.git";
+authors = "GCR contributors"
+license = "LGPL-2.0-or-later"
+description = "Library providing GTK widgets for high level crypto"
+dependencies = [ "GObject-2.0", "Gio-2.0", "Gtk-3.0", "Gck-@GCK_VERSION@", "Gcr-@GCR_VERSION@" ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable";
+
+  [dependencies."Gio-2.0"]
+  name = "Gio"
+  description = "GObject interfaces and objects"
+  docs_url = "https://developer.gnome.org/gio/stable";
+
+  [dependencies."Gtk-3.0"]
+  name = "Gtk"
+  description = "The GTK UI toolkit"
+  docs_url = "https://docs.gtk.org/gtk4/";
+
+  [dependencies."Gck-@GCK_VERSION@"]
+  name = "Gck"
+  description = "GObject bindings for PKCS#11"
+
+  [dependencies."Gcr-@GCR_VERSION@"]
+  name = "Gcr"
+  description = "GObject library for high level crypto parsing"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gcr/-/blob/master/";
+
+[extra]
+content_files = [
+  'widget-gallery.md',
+]
+content_images = [
+  'images/certificate-widget.png',
+  'images/combo-selector.png',
+  'images/import-button.png',
+  'images/key-widget.png',
+  'images/list-selector.png',
+  'images/tree-selector.png',
+  'images/viewer-widget.png',
+]
diff --git a/docs/reference/gcr/images/certificate-widget.png b/docs/ui/images/certificate-widget.png
similarity index 100%
rename from docs/reference/gcr/images/certificate-widget.png
rename to docs/ui/images/certificate-widget.png
diff --git a/docs/reference/gcr/images/combo-selector.png b/docs/ui/images/combo-selector.png
similarity index 100%
rename from docs/reference/gcr/images/combo-selector.png
rename to docs/ui/images/combo-selector.png
diff --git a/docs/reference/gcr/images/import-button.png b/docs/ui/images/import-button.png
similarity index 100%
rename from docs/reference/gcr/images/import-button.png
rename to docs/ui/images/import-button.png
diff --git a/docs/reference/gcr/images/key-widget.png b/docs/ui/images/key-widget.png
similarity index 100%
rename from docs/reference/gcr/images/key-widget.png
rename to docs/ui/images/key-widget.png
diff --git a/docs/reference/gcr/images/list-selector.png b/docs/ui/images/list-selector.png
similarity index 100%
rename from docs/reference/gcr/images/list-selector.png
rename to docs/ui/images/list-selector.png
diff --git a/docs/reference/gcr/images/tree-selector.png b/docs/ui/images/tree-selector.png
similarity index 100%
rename from docs/reference/gcr/images/tree-selector.png
rename to docs/ui/images/tree-selector.png
diff --git a/docs/reference/gcr/images/viewer-widget.png b/docs/ui/images/viewer-widget.png
similarity index 100%
rename from docs/reference/gcr/images/viewer-widget.png
rename to docs/ui/images/viewer-widget.png
diff --git a/docs/ui/meson.build b/docs/ui/meson.build
new file mode 100644
index 0000000..2b6d73d
--- /dev/null
+++ b/docs/ui/meson.build
@@ -0,0 +1,33 @@
+gcr_ui_content_files = [
+  'widget-gallery.md',
+]
+
+gcr_ui_toml = configure_file(
+  input: 'gcr-ui.toml.in',
+  output: '@BASENAME@',
+  configuration: {
+    'GCR_VERSION': gcr_major_version,
+    'GCK_VERSION': gck_major_version,
+  },
+)
+
+gcr_ui_docs = custom_target('gcr-ui-docs',
+  input: gcr_ui_gir[0],
+  output: 'gcr-ui-@0@'.format(gcr_major_version),
+  command: [
+    gi_docgen,
+    'generate',
+    '--quiet',
+    '--fatal-warnings',
+    '--add-include-path=@0@'.format(source_root / 'gcr'),
+    '--config', gcr_ui_toml,
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT@',
+  ],
+  depend_files: [ gcr_ui_toml, gcr_ui_content_files ],
+  build_by_default: true,
+  install: true,
+  install_dir: get_option('datadir') / 'doc',
+)
diff --git a/docs/ui/widget-gallery.md b/docs/ui/widget-gallery.md
new file mode 100644
index 0000000..27e1e90
--- /dev/null
+++ b/docs/ui/widget-gallery.md
@@ -0,0 +1,20 @@
+Title: Widget gallery
+
+Widget gallery
+==============
+
+Selector widgets
+----------------
+[![combo-selector](combo-selector.png)](class.ComboSelector.html)
+[![list-selector](list-selector.png)](class.ListSelector.html)
+[![tree-selector](tree-selector.png)](class.TreeSelector.html)
+
+Display widgets
+---------------
+[![certificate-widget](certificate-widget.png)](class.CertificateWidget.html)
+[![key-widget](key-widget.png)](class.KeyWidget.html)
+[![viewer-widget](viewer-widget.png)](class.ViewerWidget.html)
+
+Import widgets
+--------------
+[![import-button](import-button.png)](class.ImportButton.html)
diff --git a/gck/gck-attributes.c b/gck/gck-attributes.c
index 8612a28..de10a67 100644
--- a/gck/gck-attributes.c
+++ b/gck/gck-attributes.c
@@ -32,16 +32,18 @@
 #include <string.h>
 
 /**
- * SECTION:gck-attribute
- * @title: GckAttribute
- * @short_description: A PKCS11 attribute.
+ * GckAttribute:
+ * @type: The attribute type, such as `CKA_LABEL`.
+ * @value: (array length=length): The value of the attribute. May be %NULL.
+ * @length: The length of the attribute. May be [const@INVALID] if the
+ * attribute is invalid.
  *
- * This structure represents a PKCS11 CK_ATTRIBUTE. These attributes contain i
- * about a PKCS11 object. Use gck_object_get() or gck_object_set() to set and
- * attributes on an object.
+ * This structure represents a PKCS#11 `CK_ATTRIBUTE`. These attributes contain
+ * information about a PKCS#11 object. Use [method Object get] or
+ * [method Object set] to set and attributes on an object.
  *
- * Although you are free to allocate a #GckAttribute in your own code, no functions in
- * this library will operate on such an attribute.
+ * Although you are free to allocate a `GckAttribute` in your own code, no
+ * functions in this library will operate on such an attribute.
  */
 
 G_STATIC_ASSERT (sizeof (GckAttribute) == sizeof (CK_ATTRIBUTE));
@@ -156,7 +158,7 @@ G_DEFINE_BOXED_TYPE (GckBuilder, gck_builder,
  * GckBuilder:
  *
  * A builder for a set of attributes. Add attributes to a builder, and then use
- * gck_builder_end() to get the completed #GckAttributes.
+ * [method Builder end] to get the completed [struct@Attributes].
  *
  * The fields of #GckBuilder are private and not to be accessed directly.
  */
@@ -166,7 +168,7 @@ G_DEFINE_BOXED_TYPE (GckBuilder, gck_builder,
  * @GCK_BUILDER_NONE: no special flags
  * @GCK_BUILDER_SECURE_MEMORY: use non-pageable memory for the values of the attributes
  *
- * Flags to be used with a gck_builder_init_full() and gck_builder_new().
+ * Flags to be used with a [method@Builder.init_full] and [ctor Builder new].
  */
 
 /**
@@ -174,19 +176,19 @@ G_DEFINE_BOXED_TYPE (GckBuilder, gck_builder,
  *
  * Values that can be assigned to a #GckBuilder allocated on the stack.
  *
- * <informalexample><programlisting>
+ * ```c
  * GckBuilder builder = GCK_BUILDER_INIT;
- * </programlisting></informalexample>
+ * ```
  */
 
 /**
  * gck_builder_new:
  * @flags: flags for the new builder
  *
- * Create a new #GckBuilder not allocated on the stack, so it can be shared
+ * Create a new `GckBuilder` not allocated on the stack, so it can be shared
  * across a single scope, and referenced / unreferenced.
  *
- * Normally a #GckBuilder is created on the stack, and simply initialized.
+ * Normally a `GckBuilder` is created on the stack, and simply initialized.
  *
  * If the %GCK_BUILDER_SECURE_MEMORY flag is specified then non-pageable memory
  * will be used for the various values of the attributes in the builder
@@ -209,7 +211,7 @@ gck_builder_new (GckBuilderFlags flags)
  * gck_builder_ref:
  * @builder: the builder
  *
- * Add a reference to a builder that was created with gck_builder_new(). The
+ * Add a reference to a builder that was created with [ctor Builder new]. The
  * builder must later be unreferenced again with gck_builder_unref().
  *
  * It is an error to use this function on builders that were allocated on the
@@ -289,8 +291,8 @@ gck_builder_init_full (GckBuilder *builder,
  * This is equivalent to initializing a builder variable with the
  * %GCK_BUILDER_INIT constant, or setting it to zeroed memory.
  *
- * <informalexample><programlisting>
- * /<!-- -->* Equivalent ways of initializing a GckBuilder *<!-- -->/
+ * ```c
+ * // Equivalent ways of initializing a GckBuilder
  * GckBuilder builder = GCK_BUILDER_INIT;
  * GckBuilder builder2;
  * GckBuilder builder3;
@@ -298,7 +300,7 @@ gck_builder_init_full (GckBuilder *builder,
  * gck_builder_init (&builder2);
  *
  * memset (&builder3, 0, sizeof (builder3));
- * </programlisting></informalexample>
+ * ```
  */
 void
 gck_builder_init (GckBuilder *builder)
@@ -387,7 +389,7 @@ builder_copy (GckBuilder *builder,
  * @builder: the builder to copy
  *
  * Make a copy of the builder and its state. The new builder is allocated
- * with gck_builder_new() and should be freed with gck_builder_unref().
+ * with [ctor Builder new] and should be freed with gck_builder_unref().
  *
  * Attribute value memory is automatically shared between the two builders,
  * and is only freed when both are gone.
@@ -428,8 +430,8 @@ gck_builder_copy (GckBuilder *builder)
  * using the standard GLib memory allocation routines.
  *
  * %NULL may be specified for the @value argument, in which case an empty
- * attribute is created. GCK_INVALID may be specified for the length, in
- * which case an invalid attribute is created in the PKCS\#11 style.
+ * attribute is created. [const@INVALID] may be specified for the length, in
+ * which case an invalid attribute is created in the PKCS#11 style.
  */
 void
 gck_builder_take_data (GckBuilder *builder,
@@ -474,8 +476,8 @@ gck_builder_take_data (GckBuilder *builder,
  * The memory in @value is copied by the builder.
  *
  * %NULL may be specified for the @value argument, in which case an empty
- * attribute is created. GCK_INVALID may be specified for the length, in
- * which case an invalid attribute is created in the PKCS\#11 style.
+ * attribute is created. [const@INVALID] may be specified for the length, in
+ * which case an invalid attribute is created in the PKCS#11 style.
  */
 void
 gck_builder_add_data (GckBuilder *builder,
@@ -516,8 +518,8 @@ gck_builder_add_data (GckBuilder *builder,
  * The memory in @value is copied by the builder.
  *
  * %NULL may be specified for the @value argument, in which case an empty
- * attribute is created. GCK_INVALID may be specified for the length, in
- * which case an invalid attribute is created in the PKCS\#11 style.
+ * attribute is created. [const@INVALID] may be specified for the length, in
+ * which case an invalid attribute is created in the PKCS#11 style.
  */
 void
 gck_builder_set_data (GckBuilder *builder,
@@ -584,7 +586,7 @@ gck_builder_set_empty (GckBuilder *builder,
  * @builder: the builder
  * @attr_type: the new attribute type
  *
- * Add a new attribute to the builder that is invalid in the PKCS\#11 sense.
+ * Add a new attribute to the builder that is invalid in the PKCS#11 sense.
  * Unconditionally adds a new attribute, even if one with the same @attr_type
  * already exists.
  */
@@ -605,7 +607,7 @@ gck_builder_add_invalid (GckBuilder *builder,
  * @builder: the builder
  * @attr_type: the attribute type
  *
- * Set an attribute on the builder that is invalid in the PKCS\#11 sense.
+ * Set an attribute on the builder that is invalid in the PKCS#11 sense.
  * If an attribute with @attr_type already exists in the builder then it is
  * changed to the new value, otherwise an attribute is added.
  */
@@ -810,7 +812,7 @@ gck_builder_set_string (GckBuilder *builder,
  * or not an attribute with the same type already exists on the builder.
  *
  * The @attr attribute must have been created or owned by the Gck library.
- * If you call this function on an arbitrary #GckAttribute that is allocated on
+ * If you call this function on an arbitrary `GckAttribute` that is allocated on
  * the stack or elsewhere, then this will result in undefined behavior.
  *
  * As an optimization, the attribute memory value is automatically shared
@@ -856,7 +858,7 @@ gck_builder_add_all (GckBuilder *builder,
  * @builder: the builder
  * @attrs: the attributes to add
  * @only_type: the first type of attribute to add
- * @...: the remaining attribute types to add, ending with %GCK_INVALID
+ * @...: the remaining attribute types to add, ending with [const@INVALID]
  *
  * Add the attributes specified in the argument list from @attrs to the
  * builder. The attributes are added uncondititionally whether or not
@@ -864,10 +866,10 @@ gck_builder_add_all (GckBuilder *builder,
  *
  * The variable arguments must be unsigned longs.
  *
- * <informalexample><programlisting>
- * /<!-- -->* Add the CKA_ID and CKA_CLASS attributes from attrs to builder *<!-- -->/
+ * ```c
+ * // Add the CKA_ID and CKA_CLASS attributes from attrs to builder
  * gck_builder_add_only (builder, attrs, CKA_ID, CKA_CLASS, GCK_INVALID);
- * </programlisting></informalexample>
+ * ```
  *
  * As an optimization, the attribute memory values are automatically shared
  * between the attributes and the builder.
@@ -908,11 +910,11 @@ gck_builder_add_only (GckBuilder *builder,
  * builder. The attributes are added uncondititionally whether or not
  * attributes with the same types already exist in the builder.
  *
- * <informalexample><programlisting>
- * /<!-- -->* Add the CKA_ID and CKA_CLASS attributes from attrs to builder *<!-- -->/
+ * ```c
+ * // Add the CKA_ID and CKA_CLASS attributes from attrs to builder
  * gulong only[] = { CKA_ID, CKA_CLASS };
  * gck_builder_add_onlyv (builder, attrs, only, 2);
- * </programlisting></informalexample>
+ * ```
  *
  * As an optimization, the attribute memory values are automatically shared
  * between the attributes and the builder.
@@ -942,7 +944,7 @@ gck_builder_add_onlyv (GckBuilder *builder,
  * @builder: the builder
  * @attrs: the attributes to add
  * @except_type: the first type of attribute to to exclude
- * @...: the remaining attribute types to exclude, ending with %GCK_INVALID
+ * @...: the remaining attribute types to exclude, ending with [const@INVALID]
  *
  * Add the attributes in @attrs to the builder, with the exception of those
  * in the argument list. The attributes are added uncondititionally whether or
@@ -950,10 +952,10 @@ gck_builder_add_onlyv (GckBuilder *builder,
  *
  * The variable arguments must be unsigned longs.
  *
- * <informalexample><programlisting>
- * /<!-- -->* Add all attributes in attrs except CKA_CLASS to the builder *<!-- -->/
+ * ```c
+ * // Add all attributes in attrs except CKA_CLASS to the builder
  * gck_builder_add_except (builder, attrs, CKA_CLASS, GCK_INVALID);
- * </programlisting></informalexample>
+ * ```
  *
  * As an optimization, the attribute memory values are automatically shared
  * between the attributes and the builder.
@@ -995,11 +997,11 @@ gck_builder_add_except (GckBuilder *builder,
  * uncondititionally whether or not attributes with the same types already
  * exist in the builder.
  *
- * <informalexample><programlisting>
- * /<!-- -->* Add all attributes in attrs except CKA_CLASS to the builder *<!-- -->/
- * gulong except_types[] = { CKA_CLASS };
+ * ```c
+ * // Add all attributes in attrs except CKA_CLASS to the builder
+ * unsigned long except_types[] = { CKA_CLASS };
  * gck_builder_add_exceptv (builder, attrs, except_types, 1);
- * </programlisting></informalexample>
+ * ```
  *
  * As an optimization, the attribute memory values are automatically shared
  * between the attributes and the builder.
@@ -1057,12 +1059,12 @@ gck_builder_set_all (GckBuilder *builder,
  * @attr_type: the type of attribute to find
  *
  * Find an attribute in the builder. Both valid and invalid attributes (in
- * the PKCS\#11 sense) are returned. If multiple attributes exist for the given
+ * the PKCS#11 sense) are returned. If multiple attributes exist for the given
  * attribute type, then the first one is returned.
  *
- * The returned #GckAttribute is owned by the builder and may not be modified
- * in any way. It is only valid until another attribute is added to or set on
- * the builder, or until the builder is cleared or unreferenced.
+ * The returned [struct@Attribute] is owned by the builder and may not be
+ * modified in any way. It is only valid until another attribute is added to or
+ * set on the builder, or until the builder is cleared or unreferenced.
  *
  * Returns: the attribute or %NULL if not found
  */
@@ -1102,7 +1104,7 @@ find_attribute_boolean (GckAttribute *attrs,
  * @value: (out): the location to place the found value
  *
  * Find a boolean attribute in the builder that has the type @attr_type, is
- * of the correct boolean size, and is not invalid in the PKCS\#11 sense.
+ * of the correct boolean size, and is not invalid in the PKCS#11 sense.
  * If multiple attributes exist for the given attribute type, then the first\
  * one is returned.
  *
@@ -1146,8 +1148,8 @@ find_attribute_ulong (GckAttribute *attrs,
  * @value: (out): the location to place the found value
  *
  * Find a unsigned long attribute in the builder that has the type @attr_type,
- * is of the correct unsigned long size, and is not invalid in the PKCS\#11 sense.
- * If multiple attributes exist for the given attribute type, then the first\
+ * is of the correct unsigned long size, and is not invalid in the PKCS#11 sense.
+ * If multiple attributes exist for the given attribute type, then the first
  * one is returned.
  *
  * Returns: whether a valid unsigned long attribute was found
@@ -1195,7 +1197,7 @@ find_attribute_string (GckAttribute *attrs,
  * @value: (out): the location to place the found value
  *
  * Find a string attribute in the builder that has the type @attr_type, has a
- * non %NULL value pointer, and is not invalid in the PKCS\#11 sense.
+ * non %NULL value pointer, and is not invalid in the PKCS#11 sense.
  * If multiple attributes exist for the given attribute type, then the first
  * one is returned.
  *
@@ -1240,7 +1242,7 @@ find_attribute_date (GckAttribute *attrs,
  * @value: (out): the location to place the found value
  *
  * Find a date attribute in the builder that has the type @attr_type, is of
- * the correct date size, and is not invalid in the PKCS\#11 sense.
+ * the correct date size, and is not invalid in the PKCS#11 sense.
  * If multiple attributes exist for the given attribute type, then the first
  * one is returned.
  *
@@ -1308,7 +1310,7 @@ gck_builder_steal (GckBuilder *builder)
  *
  * Complete the #GckBuilder, and return the attributes contained in the builder.
  * The #GckBuilder will be cleared after this function call, and it is no
- * longer necessary to use gck_builder_clear() on it, although it is also
+ * longer necessary to use [method@Builder.clear] on it, although it is also
  * permitted. The builder may be used again to build another set of attributes
  * after this function call.
  *
@@ -1366,21 +1368,12 @@ gck_builder_clear (GckBuilder *builder)
        real->array = NULL;
 }
 
-/**
- * GckAttribute:
- * @type: The attribute type, such as CKA_LABEL.
- * @value: (array length=length): The value of the attribute. May be %NULL.
- * @length: The length of the attribute. May be GCK_INVALID if the attribute is invalid.
- *
- * This structure represents a PKCS11 CK_ATTRIBUTE.
- */
-
 /**
  * gck_attribute_is_invalid:
  * @attr: The attribute to check.
  *
- * Check if the PKCS\#11 attribute represents 'invalid' or 'not found'
- * according to the PKCS\#11 spec. That is, having length
+ * Check if the PKCS#11 attribute represents 'invalid' or 'not found'
+ * according to the PKCS#11 spec. That is, having length
  * of (CK_ULONG)-1.
  *
  * Return value: Whether the attribute represents invalid or not.
@@ -1396,7 +1389,7 @@ gck_attribute_is_invalid (const GckAttribute *attr)
  * gck_attribute_get_boolean:
  * @attr: The attribute to retrieve value from.
  *
- * Get the CK_BBOOL of a PKCS\#11 attribute. No conversion
+ * Get the CK_BBOOL of a PKCS#11 attribute. No conversion
  * is performed. It is an error to pass an attribute to this
  * function unless you're know it's supposed to contain a
  * boolean value.
@@ -1420,7 +1413,7 @@ gck_attribute_get_boolean (const GckAttribute *attr)
  * gck_attribute_get_ulong:
  * @attr: The attribute to retrieve value from.
  *
- * Get the CK_ULONG value of a PKCS\#11 attribute. No
+ * Get the CK_ULONG value of a PKCS#11 attribute. No
  * conversion is performed. It is an error to pass an attribute
  * to this function unless you're know it's supposed to contain
  * a value of the right type.
@@ -1444,7 +1437,7 @@ gck_attribute_get_ulong (const GckAttribute *attr)
  * gck_attribute_get_string:
  * @attr: The attribute to retrieve value from.
  *
- * Get the string value of a PKCS\#11 attribute. No
+ * Get the string value of a PKCS#11 attribute. No
  * conversion is performed. It is an error to pass an attribute
  * to this function unless you're know it's supposed to contain
  * a value of the right type.
@@ -1470,7 +1463,7 @@ gck_attribute_get_string (const GckAttribute *attr)
  * @attr: The attribute to retrieve value from.
  * @value: The date value to fill in with the parsed date.
  *
- * Get the CK_DATE of a PKCS\#11 attribute. No
+ * Get the CK_DATE of a PKCS#11 attribute. No
  * conversion is performed. It is an error to pass an attribute
  * to this function unless you're know it's supposed to contain
  * a value of the right type.
@@ -1546,14 +1539,14 @@ gck_attribute_get_data (const GckAttribute *attr,
 /**
  * gck_attribute_init: (skip)
  * @attr: an uninitialized attribute
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: (array length=length): The raw value of the attribute.
  * @length: The length of the raw value.
  *
- * Initialize a PKCS\#11 attribute. This copies the value memory
+ * Initialize a PKCS#11 attribute. This copies the value memory
  * into an internal buffer.
  *
- * When done with the attribute you should use gck_attribute_clear()
+ * When done with the attribute you should use [method@Attribute.clear]
  * to free the internal memory.
  **/
 void
@@ -1580,13 +1573,13 @@ gck_attribute_init (GckAttribute *attr,
 /**
  * gck_attribute_init_invalid: (skip)
  * @attr: an uninitialized attribute
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  *
- * Initialize a PKCS\#11 attribute to an 'invalid' or 'not found'
+ * Initialize a PKCS#11 attribute to an 'invalid' or 'not found'
  * state. Specifically this sets the value length to (CK_ULONG)-1
- * as specified in the PKCS\#11 specification.
+ * as specified in the PKCS#11 specification.
  *
- * When done with the attribute you should use gck_attribute_clear()
+ * When done with the attribute you should use [method@Attribute.clear]
  * to free the internal memory.
  **/
 void
@@ -1602,12 +1595,12 @@ gck_attribute_init_invalid (GckAttribute *attr,
 /**
  * gck_attribute_init_empty: (skip)
  * @attr: an uninitialized attribute
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  *
- * Initialize a PKCS\#11 attribute to an empty state. The attribute
+ * Initialize a PKCS#11 attribute to an empty state. The attribute
  * type will be set, but no data will be set.
  *
- * When done with the attribute you should use gck_attribute_clear()
+ * When done with the attribute you should use [method@Attribute.clear]
  * to free the internal memory.
  **/
 void
@@ -1623,13 +1616,13 @@ gck_attribute_init_empty (GckAttribute *attr, gulong attr_type)
 /**
  * gck_attribute_init_boolean: (skip)
  * @attr: an uninitialized attribute
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the boolean value of the attribute
  *
- * Initialize a PKCS\#11 attribute to boolean. This will result
- * in a CK_BBOOL attribute from the PKCS\#11 specs.
+ * Initialize a PKCS#11 attribute to boolean. This will result
+ * in a CK_BBOOL attribute from the PKCS#11 specs.
  *
- * When done with the attribute you should use gck_attribute_clear()
+ * When done with the attribute you should use [method@Attribute.clear]
  * to free the internal memory.
  **/
 void
@@ -1645,13 +1638,13 @@ gck_attribute_init_boolean (GckAttribute *attr,
 /**
  * gck_attribute_init_date: (skip)
  * @attr: an uninitialized attribute
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the date value of the attribute
  *
- * Initialize a PKCS\#11 attribute to a date. This will result
- * in a CK_DATE attribute from the PKCS\#11 specs.
+ * Initialize a PKCS#11 attribute to a date. This will result
+ * in a CK_DATE attribute from the PKCS#11 specs.
  *
- * When done with the attribute you should use gck_attribute_clear()
+ * When done with the attribute you should use [method@Attribute.clear]
  * to free the internal memory.
  **/
 void
@@ -1671,13 +1664,13 @@ gck_attribute_init_date (GckAttribute *attr,
 /**
  * gck_attribute_init_ulong: (skip)
  * @attr: an uninitialized attribute
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the ulong value of the attribute
  *
- * Initialize a PKCS\#11 attribute to a unsigned long. This will result
- * in a CK_ULONG attribute from the PKCS\#11 specs.
+ * Initialize a PKCS#11 attribute to a unsigned long. This will result
+ * in a CK_ULONG attribute from the PKCS#11 specs.
  *
- * When done with the attribute you should use gck_attribute_clear()
+ * When done with the attribute you should use [method@Attribute.clear]
  * to free the internal memory.
  **/
 void
@@ -1693,15 +1686,15 @@ gck_attribute_init_ulong (GckAttribute *attr,
 /**
  * gck_attribute_init_string: (skip)
  * @attr: an uninitialized attribute
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the null terminated string value of the attribute
  *
- * Initialize a PKCS\#11 attribute to a string. This will result
+ * Initialize a PKCS#11 attribute to a string. This will result
  * in an attribute containing the text, but not the null terminator.
  * The text in the attribute will be of the same encoding as you pass
  * to this function.
  *
- * When done with the attribute you should use gck_attribute_clear()
+ * When done with the attribute you should use [method@Attribute.clear]
  * to free the internal memory.
  **/
 void
@@ -1719,11 +1712,11 @@ G_DEFINE_BOXED_TYPE (GckAttribute, gck_attribute,
 
 /**
  * gck_attribute_new:
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the raw value of the attribute
  * @length: the length of the attribute
  *
- * Create a new PKCS\#11 attribute. The value will be copied
+ * Create a new PKCS#11 attribute. The value will be copied
  * into the new attribute.
  *
  * Returns: (transfer full): the new attribute; when done with the attribute
@@ -1741,11 +1734,11 @@ gck_attribute_new (gulong attr_type,
 
 /**
  * gck_attribute_new_invalid:
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  *
- * Create a new PKCS\#11 attribute as 'invalid' or 'not found'
+ * Create a new PKCS#11 attribute as 'invalid' or 'not found'
  * state. Specifically this sets the value length to (CK_ULONG)-1
- * as specified in the PKCS\#11 specification.
+ * as specified in the PKCS#11 specification.
  *
  * Returns: (transfer full): the new attribute; when done with the attribute
  *          use gck_attribute_free() to free it
@@ -1760,9 +1753,9 @@ gck_attribute_new_invalid (gulong attr_type)
 
 /**
  * gck_attribute_new_empty:
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  *
- * Create a new PKCS\#11 attribute with empty data.
+ * Create a new PKCS#11 attribute with empty data.
  *
  * Returns: (transfer full): the new attribute; when done with the attribute
  *          use gck_attribute_free() to free it
@@ -1777,11 +1770,11 @@ gck_attribute_new_empty (gulong attr_type)
 
 /**
  * gck_attribute_new_boolean:
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the boolean value of the attribute
  *
- * Initialize a PKCS\#11 attribute to boolean. This will result
- * in a CK_BBOOL attribute from the PKCS\#11 specs.
+ * Initialize a PKCS#11 attribute to boolean. This will result
+ * in a CK_BBOOL attribute from the PKCS#11 specs.
  *
  * Returns: (transfer full): the new attribute; when done with the attribute u
  *          gck_attribute_free() to free it
@@ -1797,11 +1790,11 @@ gck_attribute_new_boolean (gulong attr_type,
 
 /**
  * gck_attribute_new_date:
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the date value of the attribute
  *
- * Initialize a PKCS\#11 attribute to a date. This will result
- * in a CK_DATE attribute from the PKCS\#11 specs.
+ * Initialize a PKCS#11 attribute to a date. This will result
+ * in a CK_DATE attribute from the PKCS#11 specs.
  *
  * Returns: (transfer full): the new attribute; when done with the attribute u
  *          gck_attribute_free() to free it
@@ -1817,11 +1810,11 @@ gck_attribute_new_date (gulong attr_type,
 
 /**
  * gck_attribute_new_ulong:
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the ulong value of the attribute
  *
- * Initialize a PKCS\#11 attribute to a unsigned long. This will result
- * in a CK_ULONG attribute from the PKCS\#11 specs.
+ * Initialize a PKCS#11 attribute to a unsigned long. This will result
+ * in a `CK_ULONG` attribute from the PKCS#11 specs.
  *
  * Returns: (transfer full): the new attribute; when done with the attribute u
  *          gck_attribute_free() to free it
@@ -1837,10 +1830,10 @@ gck_attribute_new_ulong (gulong attr_type,
 
 /**
  * gck_attribute_new_string:
- * @attr_type: the PKCS\#11 attribute type to set on the attribute
+ * @attr_type: the PKCS#11 attribute type to set on the attribute
  * @value: the null-terminated string value of the attribute
  *
- * Initialize a PKCS\#11 attribute to a string. This will result
+ * Initialize a PKCS#11 attribute to a string. This will result
  * in an attribute containing the text, but not the null terminator.
  * The text in the attribute will be of the same encoding as you pass
  * to this function.
@@ -1861,7 +1854,7 @@ gck_attribute_new_string (gulong attr_type,
  * gck_attribute_dup:
  * @attr: the attribute to duplicate
  *
- * Duplicate the PKCS\#11 attribute. All value memory is
+ * Duplicate the PKCS#11 attribute. All value memory is
  * also copied.
  *
  * The @attr must have been allocated or initialized by a Gck function or
@@ -1888,12 +1881,12 @@ gck_attribute_dup (const GckAttribute *attr)
  * @dest: An uninitialized attribute.
  * @src: An attribute to copy.
  *
- * Initialize a PKCS\#11 attribute as a copy of another attribute.
+ * Initialize a PKCS#11 attribute as a copy of another attribute.
  * This copies the value memory as well.
  *
  * When done with the copied attribute you should use
- * gck_attribute_clear() to free the internal memory.
- **/
+ * [method@Attribute.clear] to free the internal memory.
+ */
 void
 gck_attribute_init_copy (GckAttribute *dest,
                          const GckAttribute *src)
@@ -1941,7 +1934,7 @@ gck_attribute_clear (GckAttribute *attr)
  * @attr: (type Gck.Attribute): attribute to free
  *
  * Free an attribute and its allocated memory. These is usually
- * used with attributes that are allocated by gck_attribute_new()
+ * used with attributes that are allocated by [ctor Attribute new]
  * or a similar function.
  **/
 void
@@ -2011,20 +2004,14 @@ gck_attribute_hash (gconstpointer attr)
        return h;
 }
 
-/**
- * SECTION:gck-attributes
- * @title: GckAttributes
- * @short_description: A set of PKCS11 attributes.
- *
- * A set of GckAttribute structures. These attributes contain information
- * about a PKCS11 object. Use gck_object_get() or gck_object_set() to set and retrieve
- * attributes on an object.
- */
-
 /**
  * GckAttributes:
  *
- * A set of GckAttribute structures.
+ * A set of [struct@Attribute] structures.
+ *
+ * These attributes contain information about a PKCS11 object. Use
+ * [method Object get] or [method Object set] to set and retrieve attributes on
+ * an object.
  */
 
 /**
@@ -2032,7 +2019,8 @@ gck_attribute_hash (gconstpointer attr)
  * @data: Memory to allocate or deallocate.
  * @length: New length of memory.
  *
- * An allocator used to allocate data for the attributes in this GckAttributes set.
+ * An allocator used to allocate data for the attributes in this
+ * [struct@Attributes] set.
  *
  * This is a function that acts like g_realloc. Specifically it frees when length is
  * set to zero, it allocates when data is set to %NULL, and it reallocates when both
@@ -2058,7 +2046,7 @@ gck_attributes_get_boxed_type (void)
  *
  * Creates an GckAttributes array with empty attributes
  *
- * Terminate the argument list with %GCK_INVALID.
+ * Terminate the argument list with [const@INVALID].
  *
  * The returned set of attributes is floating, and should either be passed to
  * another gck library function which consumes this floating reference, or if
@@ -2092,7 +2080,7 @@ gck_attributes_new_empty (gulong first_type,
  *
  * Get attribute at the specified index in the attribute array.
  *
- * Use gck_attributes_count() to determine how many attributes are
+ * Use [method@Attributes.count] to determine how many attributes are
  * in the array.
  *
  * Returns: (transfer none): the specified attribute
@@ -2252,12 +2240,12 @@ gck_attributes_ref (GckAttributes *attrs)
  * gck_attributes_ref_sink:
  * @attrs: an attribute array
  *
- * #GckAttributes uses a floating reference count system. gck_builder_end()
- * and gck_attributes_new_empty() both return floating references.
+ * #GckAttributes uses a floating reference count system. [method Builder end]
+ * and [ctor@Attributes.new_empty] both return floating references.
  *
- * Calling gck_attributes_ref_sink() on a #GckAttributes with a floating
+ * Calling this function on a `GckAttributes` with a floating
  * reference will convert the floating reference into a full reference.
- * Calling gck_attributes_ref_sink() on a non-floating #GckAttributes results
+ * Calling this function on a non-floating `GckAttributes` results
  * in an additional normal reference being added.
  *
  * In other words, if the @attrs is floating, then this call "assumes
@@ -2822,9 +2810,9 @@ gck_attributes_to_string (GckAttributes *attrs)
 
 /**
  * gck_attributes_new:
- * @reserved: Should be set to always be GCK_INVALID
+ * @reserved: Should be set to always be [const@INVALID]
  *
- * Create a new empty GckAttributes array.
+ * Create a new empty `GckAttributes` array.
  *
  * The returned set of attributes is floating, and should either be passed to
  * another gck library function which consumes this floating reference, or if
@@ -2847,7 +2835,7 @@ gck_attributes_new (gulong reserved)
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_set_all() instead.
+ * Deprecated: 3.4: Use [method@Builder.set_all] instead.
  *
  * Returns: returns %NULL
  **/
@@ -2865,7 +2853,7 @@ gck_attributes_new_full (GckAllocator allocator)
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_set_all() instead.
+ * Deprecated: 3.4: Use [method@Builder.set_all] instead.
  *
  * Returns: (transfer none): returns %NULL
  **/
@@ -2884,7 +2872,7 @@ gck_attributes_add (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_set_data() instead.
+ * Deprecated: 3.4: Use [method@Builder.set_data] instead.
  **/
 void
 gck_attributes_set (GckAttributes *attrs,
@@ -2902,7 +2890,7 @@ gck_attributes_set (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_add_data() instead.
+ * Deprecated: 3.4: Use [method@Builder.add_data] instead.
  *
  * Returns: (transfer none): returns %NULL
  **/
@@ -2923,7 +2911,7 @@ gck_attributes_add_data (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_add_invalid() instead
+ * Deprecated: 3.4: Use [method@Builder.add_invalid] instead
  *
  * Returns: (transfer none): returns %NULL
  **/
@@ -2942,7 +2930,7 @@ gck_attributes_add_invalid (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_add_empty() instead.
+ * Deprecated: 3.4: Use [method@Builder.add_empty] instead.
  *
  * Returns: (transfer none): returns %NULL
  **/
@@ -2962,7 +2950,7 @@ gck_attributes_add_empty (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_add_boolean() instead.
+ * Deprecated: 3.4: Use [method@Builder.add_boolean] instead.
  *
  * Returns: (transfer none): returns %NULL
  **/
@@ -2983,7 +2971,7 @@ gck_attributes_add_boolean (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_set_boolean() instead.
+ * Deprecated: 3.4: Use [method@Builder.set_boolean] instead.
  */
 void
 gck_attributes_set_boolean (GckAttributes *attrs,
@@ -3002,7 +2990,7 @@ gck_attributes_set_boolean (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_add_string() instead.
+ * Deprecated: 3.4: Use [method@Builder.add_string] instead.
  *
  * Returns: (transfer none): returns %NULL
  **/
@@ -3023,7 +3011,7 @@ gck_attributes_add_string (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_set_string() instead.
+ * Deprecated: 3.4: Use [method@Builder.set_string] instead.
  */
 void
 gck_attributes_set_string (GckAttributes *attrs,
@@ -3041,7 +3029,7 @@ gck_attributes_set_string (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_add_date() instead.
+ * Deprecated: 3.4: Use [method@Builder.add_date] instead.
  *
  * Returns: (transfer none): returns %NULL
  **/
@@ -3062,7 +3050,7 @@ gck_attributes_add_date (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_set_date() instead.
+ * Deprecated: 3.4: Use [method@Builder.set_date] instead.
  */
 void
 gck_attributes_set_date (GckAttributes *attrs,
@@ -3080,7 +3068,7 @@ gck_attributes_set_date (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_add_ulong() instead.
+ * Deprecated: 3.4: Use [method@Builder.add_ulong] instead.
  *
  * Returns: (transfer none): returns %NULL
  **/
@@ -3101,7 +3089,7 @@ gck_attributes_add_ulong (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_set_ulong() instead.
+ * Deprecated: 3.4: Use [method@Builder.set_ulong] instead.
  */
 void
 gck_attributes_set_ulong (GckAttributes *attrs,
@@ -3118,7 +3106,7 @@ gck_attributes_set_ulong (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_add_all() instead.
+ * Deprecated: 3.4: Use [method@Builder.add_all] instead.
  */
 void
 gck_attributes_add_all (GckAttributes *attrs,
@@ -3134,7 +3122,7 @@ gck_attributes_add_all (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable. This method no longer does anything.
  *
- * Deprecated: 3.4: Use gck_builder_set_all() instead.
+ * Deprecated: 3.4: Use [method@Builder.set_all] instead.
  */
 void
 gck_attributes_set_all (GckAttributes *attrs,
@@ -3149,7 +3137,7 @@ gck_attributes_set_all (GckAttributes *attrs,
  *
  * #GckAttributes are now immutable, and can be used in mulitple places.
  *
- * Deprecated: 3.4: Use gck_attributes_ref() or gck_builder_add_all() instead.
+ * Deprecated: 3.4: Use gck_attributes_ref() or [method@Builder.add_all] instead.
  *
  * Returns: (transfer none): a new floating #GckAttributes
  */
diff --git a/gck/gck-enumerator.c b/gck/gck-enumerator.c
index 16a8923..c1b82ee 100644
--- a/gck/gck-enumerator.c
+++ b/gck/gck-enumerator.c
@@ -28,16 +28,14 @@
 #include <string.h>
 
 /**
- * SECTION:gck-enumerator
- * @title: GckEnumerator
- * @short_description: Enumerates through PKCS\#11 objects.
+ * GckEnumerator:
  *
- * A GckEnumerator can be used to enumerate through PKCS\#11 objects. It will
- * automatically create sessions as necessary.
+ * Can be used to enumerate through PKCS#11 objects. It will automatically
+ * create sessions as necessary.
  *
- * Use gck_modules_enumerate_objects() or gck_modules_enumerate_uri() to create
- * an enumerator. To get the objects use gck_enumerator_next() or
- * gck_enumerator_next_async() functions.
+ * Use [func@modules_enumerate_objects] or [func@modules_enumerate_uri] to
+ * create an enumerator. To get the objects, use [method Enumerator next] or
+ * [method@Enumerator.next_async] functions.
  */
 
 enum {
@@ -47,12 +45,6 @@ enum {
        PROP_CHAINED
 };
 
-/**
- * GckEnumerator:
- *
- * An object that allows enumerating of objects across modules, tokens.
- */
-
 typedef struct _GckEnumeratorResult {
        gulong handle;
        GckSession *session;
diff --git a/gck/gck-misc.c b/gck/gck-misc.c
index e44241b..1ebebb4 100644
--- a/gck/gck-misc.c
+++ b/gck/gck-misc.c
@@ -1,4 +1,3 @@
-/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /* gck-misc.c - the GObject PKCS#11 wrapper library
 
    Copyright (C) 2008, Stefan Walter
@@ -35,31 +34,20 @@
 
 EGG_SECURE_DEFINE_GLIB_GLOBALS ();
 
-/**
- * SECTION:gck-library
- * @title: Library Utilities
- * @short_description: Library utilities such as version checks
- *
- * Basic library utilities such as version checks.
- */
-
 /**
  * GCK_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 Gck libarry that is being compiled
+ * Checks the version of the Gck library that is being compiled
  * against.
  *
- * <example>
- * <title>Checking the version of the Gck library</title>
- * <programlisting>
+ * ```
  * #if !GCK_CHECK_VERSION (3, 0, 0)
  * #warning Old Gck version, disabling functionality
  * #endif
- * </programlisting>
- * </example>
+ * ```
  *
  * Returns: %TRUE if the version of the GLib header files
  * is the same as or newer than the passed-in version.
@@ -83,23 +71,6 @@ EGG_SECURE_DEFINE_GLIB_GLOBALS ();
  * The micro version number of the Gck library.
  */
 
-/**
- * SECTION:gck-error
- * @title: Errors
- * @short_description: Gck Errors and error codes.
- *
- * Errors are returned as GError structures. The code member of GError
- * contains the raw PKCS11 CK_RV result value.
- */
-
-/**
- * SECTION:gck-private
- * @title: Private, not used in docs
- * @short_description: Should not show up in docs
- *
- * Should not show up in the docs
- */
-
 /**
  * GCK_INVALID:
  *
@@ -109,17 +80,20 @@ EGG_SECURE_DEFINE_GLIB_GLOBALS ();
 /**
  * GCK_VENDOR_CODE:
  *
- * Custom PKCS11 errors that originate from the gck library, are
+ * Custom PKCS#11 errors that originate from the gck library, are
  * based at this error code.
  */
 
 /**
  * GckError:
  * @GCK_ERROR_MODULE_PROBLEM: a result code that signifies there was a problem
- *                            loading a PKCS\#11 module, usually a shared library
+ *                            loading a PKCS#11 module, usually a shared library
  *
- * Various error codes. All the CKR_XXX error codes from PKCS\#11 are also
+ * Various error codes. All the `CKR_XXX` error codes from PKCS#11 are also
  * relevant error codes.
+ *
+ * Note that errors are returned as [class@GLib.Error] structures. The `code`
+ * member of the error then contains the raw PKCS#11 `CK_RV` result value.
  */
 
 /**
@@ -151,13 +125,13 @@ gck_error_get_quark (void)
 
 /**
  * gck_message_from_rv:
- * @rv: The PKCS\#11 return value to get a message for.
+ * @rv: The PKCS#11 return value to get a message for.
  *
- * Get a message for a PKCS\#11 return value or error code. Do not
- * pass CKR_OK or other such non errors to this function.
+ * Get a message for a PKCS#11 return value or error code. Do not
+ * pass `CKR_OK` or other non-errors to this function.
  *
  * Return value: The user readable message.
- **/
+ */
 const gchar*
 gck_message_from_rv (gulong rv)
 {
@@ -287,15 +261,6 @@ _gck_rv_from_error (GError *error,
        return catch_all_code;
 }
 
-/**
- * SECTION:gck-misc
- * @title: Miscellaneous Functions
- * @short_description: Other miscellaneous functions.
- *
- * A few supporting functions that come in handy when dealing with the gck
- * library or PKCS11 in general.
- */
-
 GType
 gck_list_get_boxed_type (void)
 {
@@ -353,9 +318,9 @@ gck_list_ref_copy (GList *reflist)
  * @data: The character data to turn into a null terminated string.
  * @max: The maximum length of the charater data.
  *
- * Create a string from a set of PKCS\#11 characters. This is
- * similar to g_strndup, except for that it also strips trailing
- * spaces. These space padded strings are often used in PKCS\#11
+ * Create a string from a set of PKCS#11 characters. This is
+ * similar to [func@GLib.strndup], except for that it also strips trailing
+ * spaces. These space padded strings are often used in PKCS#11
  * structures.
  *
  * If the space padded string is filled with null characters then
@@ -386,7 +351,7 @@ gck_string_from_chars (const guchar *data, gsize max)
  * @max: The maximum length of the charater buffer.
  * @string: The string to place in the buffer.
  *
- * Create a space padded PKCS\#11 string from a null terminated string.
+ * Create a space padded PKCS#11 string from a null terminated string.
  * The string must be shorter than the buffer or %FALSE will be
  * returned.
  *
@@ -441,7 +406,7 @@ _gck_ulong_equal (gconstpointer v1, gconstpointer v2)
  * @length: length of memory
  * @result: A location to store the result
  *
- * Convert CK_ULONG type memory to a boolean.
+ * Convert `CK_ULONG` type memory to a boolean.
  *
  * Returns: Whether the conversion was successful.
  */
@@ -463,7 +428,7 @@ gck_value_to_ulong (const guchar *value,
  * @length: length of memory
  * @result: A location to store the result
  *
- * Convert CK_BBOOL type memory to a boolean.
+ * Convert `CK_BBOOL` type memory to a boolean.
  *
  * Returns: Whether the conversion was successful.
  */
diff --git a/gck/gck-module.c b/gck/gck-module.c
index 1fa7584..a50f78d 100644
--- a/gck/gck-module.c
+++ b/gck/gck-module.c
@@ -34,22 +34,15 @@
 
 #include <string.h>
 
-/**
- * SECTION:gck-module
- * @title: GckModule
- * @short_description: A loaded and initialized PKCS\#11 module.
- *
- * A GckModule object holds a loaded PKCS\#11 module. A PKCS\#11 module is a shared library.
- *
- * You can load and initialize a PKCS\#11 module with the gck_module_initialize() call. If you already
- * have a loaded and initialized module that you'd like to use with the various gck functions, then
- * you can use gck_module_new().
- */
-
 /**
  * GckModule:
  *
- * Holds a loaded and initialized PKCS\#11 module.
+ * Holds a loaded PKCS#11 module. A PKCS#11 module is a shared library.
+ *
+ * You can load and initialize a PKCS#11 module with the
+ * [func@Module.initialize] call. If you already have a loaded and
+ * initialized module that you'd like to use with the various Gck functions,
+ * then you can use [ctor Module new].
  */
 
 /**
@@ -62,9 +55,9 @@
  * @library_version_major: The major version of the library.
  * @library_version_minor: The minor version of the library.
  *
- * Holds information about the PKCS&num;11 module.
+ * Holds information about the PKCS#11 module.
  *
- * This structure corresponds to CK_MODULE_INFO in the PKCS\#11 standard. The
+ * This structure corresponds to `CK_MODULE_INFO` in the PKCS#11 standard. The
  * strings are %NULL terminated for easier use.
  *
  * Use gck_module_info_free() to release this structure when done with it.
@@ -365,13 +358,13 @@ free_initialize (Initialize *args)
 
 /**
  * gck_module_initialize:
- * @path: The file system path to the PKCS\#11 module to load.
+ * @path: The file system path to the PKCS#11 module to load.
  * @cancellable: (nullable): optional cancellation object
  * @error: A location to store an error resulting from a failed load.
  *
- * Load and initialize a PKCS\#11 module represented by a GckModule object.
+ * Load and initialize a PKCS#11 module represented by a GckModule object.
  *
- * Return value: (transfer full): The loaded PKCS\#11 module or %NULL if failed.
+ * Return value: (transfer full): The loaded PKCS#11 module or %NULL if failed.
  **/
 GckModule*
 gck_module_initialize (const gchar *path,
@@ -402,13 +395,13 @@ gck_module_initialize (const gchar *path,
 
 /**
  * gck_module_initialize_async:
- * @path: the file system path to the PKCS\#11 module to load
+ * @path: the file system path to the PKCS#11 module to load
  * @cancellable: (nullable): optional cancellation object
  * @callback: a callback which will be called when the operation completes
  * @user_data: data to pass to the callback
  *
- * Asynchronously load and initialize a PKCS\#11 module represented by a
- * #GckModule object.
+ * Asynchronously load and initialize a PKCS#11 module represented by a
+ * [class@Module] object.
  **/
 void
 gck_module_initialize_async (const gchar *path,
@@ -464,13 +457,13 @@ gck_module_initialize_finish (GAsyncResult *result,
 
 /**
  * gck_module_new: (skip)
- * @funcs: Initialized PKCS\#11 function list pointer
+ * @funcs: Initialized PKCS#11 function list pointer
  *
- * Create a GckModule representing a PKCS\#11 module. It is assumed that
+ * Create a [class@Module] representing a PKCS#11 module. It is assumed that
  * this the module is already initialized. In addition it will not be
  * finalized when complete.
  *
- * Return value: The new PKCS\#11 module.
+ * Return value: The new PKCS#11 module.
  **/
 GckModule*
 gck_module_new (CK_FUNCTION_LIST_PTR funcs)
@@ -493,7 +486,7 @@ _gck_module_new_initialized (CK_FUNCTION_LIST_PTR funcs)
  * @module2: (type Gck.Module): a pointer to the second #GckModule
  *
  * Checks equality of two modules. Two GckModule objects can point to the same
- * underlying PKCS\#11 module.
+ * underlying PKCS#11 module.
  *
  * Return value: %TRUE if module1 and module2 are equal.
  *               %FALSE if either is not a GckModule.
@@ -520,8 +513,8 @@ gck_module_equal (gconstpointer module1, gconstpointer module2)
  *
  * Create a hash value for the GckModule.
  *
- * This function is intended for easily hashing a GckModule to add to
- * a GHashTable or similar data structure.
+ * This function is intended for easily hashing a [class@Module] to add to
+ * a [struct@GLib.HashTable] or similar data structure.
  *
  * Return value: An integer that can be used as a hash value, or 0 if invalid.
  **/
@@ -577,7 +570,7 @@ _gck_module_info_to_pkcs11 (GckModuleInfo* module_info, CK_INFO_PTR info)
  * gck_module_get_info:
  * @self: The module to get info for.
  *
- * Get the info about a PKCS\#11 module.
+ * Get the info about a PKCS#11 module.
  *
  * Returns: (transfer full): the module info; release this with gck_module_info_free()
  **/
@@ -654,7 +647,7 @@ gck_module_get_slots (GckModule *self, gboolean token_present)
  * @self: The module for which to get the path.
  *
  * Get the file path of this module. This may not be an absolute path, and
- * usually reflects the path passed to gck_module_initialize().
+ * usually reflects the path passed to [func@Module.initialize].
  *
  * Return value: The path, do not modify or free this value.
  **/
@@ -669,7 +662,7 @@ gck_module_get_path (GckModule *self)
  * gck_module_get_functions: (skip)
  * @self: The module for which to get the function list.
  *
- * Get the PKCS\#11 function list for the module.
+ * Get the PKCS#11 function list for the module.
  *
  * Return value: The function list, do not modify this structure.
  **/
@@ -685,7 +678,7 @@ gck_module_get_functions (GckModule *self)
  * @self: the module to match
  * @uri: the uri to match against the module
  *
- * Check whether the PKCS\#11 URI matches the module
+ * Check whether the PKCS#11 URI matches the module
  *
  * Returns: whether the URI matches or not
  */
diff --git a/gck/gck-modules.c b/gck/gck-modules.c
index 63a2e07..97d7f01 100644
--- a/gck/gck-modules.c
+++ b/gck/gck-modules.c
@@ -35,10 +35,8 @@
 #include <string.h>
 #include <stdlib.h>
 
-/**
- * SECTION:gck-modules
- * @title: GckModule lists
- * @short_description: Dealing with lists of PKCS\#11 modules.
+/*
+ * GckModule lists:
  *
  * These functions are useful for dealing with lists of modules, and performing
  * operations on all of them.
@@ -135,7 +133,7 @@ gck_modules_initialize_registered_async (GCancellable *cancellable,
  * @error: location to place an error on failure
  *
  * Finishes the asynchronous operation to initialize the registered
- * PKCS\#11 modules.
+ * PKCS#11 modules.
  *
  * Returns: (transfer full) (element-type Gck.Module): a list of newly
  * initialized #GckModule objects
@@ -197,7 +195,7 @@ gck_modules_get_slots (GList *modules, gboolean token_present)
  *
  * This call will not block but will return an enumerator immediately.
  *
- * If the @attrs #GckAttributes is floating, it is consumed.
+ * If the @attrs [struct@Attributes] is floating, it is consumed.
  *
  * Return value: (transfer full): A new enumerator, which should be released
  * with g_object_unref().
@@ -330,7 +328,7 @@ gck_modules_tokens_for_uri (GList *modules,
  *
  * Find an object that matches a URI.
  *
- * This call can block. Use gck_modules_enumerate_uri() for a non-blocking
+ * This call can block. Use [func@modules_enumerate_uri] for a non-blocking
  * version.
  *
  * Returns: (transfer full) (nullable): A new #GckObject which should be released with
@@ -367,7 +365,7 @@ gck_modules_object_for_uri (GList *modules,
  *
  * Find objects that match a URI.
  *
- * This call can block. Use gck_modules_enumerate_uri() for a non-blocking
+ * This call can block. Use [func@modules_enumerate_uri] for a non-blocking
  * version.
  *
  * Returns: (transfer full) (element-type Gck.Object): A list of #GckObject which
@@ -405,7 +403,7 @@ gck_modules_objects_for_uri (GList *modules,
  *
  * Enumerate objects that match a URI.
  *
- * This call will not block. Use the #GckEnumerator functions in order to
+ * This call will not block. Use the [class@Enumerator] functions in order to
  * get at the actual objects that match.
  *
  * Returns: (transfer full): A new #GckEnumerator, or %NULL if an error occurs.
diff --git a/gck/gck-object-cache.c b/gck/gck-object-cache.c
index fd1e170..d86867d 100644
--- a/gck/gck-object-cache.c
+++ b/gck/gck-object-cache.c
@@ -1,4 +1,3 @@
-/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /* gck-object-cache.c - the GObject PKCS#11 wrapper library
 
    Copyright (C) 2011 Collabora Ltd.
@@ -27,21 +26,14 @@
 
 #include <string.h>
 
-/**
- * SECTION:gck-object-cache
- * @title: GckObjectCache
- * @short_description: An interface which holds attributes for a PKCS\#11 object
- *
- * #GckObjectCache is an interface implemented by derived classes of
- * #GckObject to indicate which attributes they'd like an enumerator to retrieve.
- * These attributes are then cached on the object and can be retrieved through
- * the #GckObjectCache:attributes property.
- */
-
 /**
  * GckObjectCache:
  *
- * An interface implemented on an #GckObject which contains a cache of attributes.
+ * An interface implemented by derived classes of [class@Object] to indicate
+ * which attributes they'd like an enumerator to retrieve.
+ *
+ * These attributes are then cached on the object and can be retrieved through
+ * the [property@ObjectCache:attributes] property.
  */
 
 /**
@@ -52,9 +44,10 @@
  * @n_default_types: number of attribute types to be retrieved
  * @fill: virtual method to add attributes to the cache
  *
- * Interface for #GckObjectCache. If the @default_types field is set by
- * a implementing class, then the a #GckEnumerator which has been setup using
- * gck_enumerator_set_object_type()
+ * Interface for [iface@ObjectCache]. If the @default_types field is
+ * implemented by a implementing class, then that will be used by a
+ * [class@Enumerator] which has been setup using
+ * [method@Enumerator.set_object_type]
  *
  * The implementation for @populate should add the attributes to the
  * cache. It must be thread safe.
diff --git a/gck/gck-object.c b/gck/gck-object.c
index 1521626..284b1f3 100644
--- a/gck/gck-object.c
+++ b/gck/gck-object.c
@@ -27,32 +27,25 @@
 
 #include <string.h>
 
-/**
- * SECTION:gck-object
- * @title: GckObject
- * @short_description: Represents a PKCS11 object such as a key or certificate.
- *
- * A GckObject holds a handle to a PKCS11 object such as a key or certificate. Token objects
- * are stored on the token persistently. Others are transient and are called session objects.
- */
-
 /**
  * GckObject:
  *
- * Represents a PKCS11 object handle such as a key or certifiacte.
+ * Holds a handle to a PKCS11 object such as a key or certificate. Token
+ * objects are stored on the token persistently. Others are transient and are
+ * called session objects.
  */
 
 /**
  * GckObjectClass:
  * @parent: derived from this
  *
- * The class for a #GckObject.
+ * The class for a [class@Object].
  *
  * If the @attribute_types field is set by a derived class, then the a
- * #GckEnumerator which has been setup using gck_enumerator_set_object_type()
+ * #GckEnumerator which has been setup using [method@Enumerator.set_object_type]
  * with this derived type will retrieve these attributes when enumerating. In
  * this case the class must implement an 'attributes' property of boxed type
- * GCK_TYPE_ATTRIBUTES.
+ * `GCK_TYPE_ATTRIBUTES`.
  */
 
 /*
@@ -202,15 +195,15 @@ gck_object_class_init (GckObjectClass *klass)
  */
 
 /**
- * gck_object_from_handle:
+ * gck_object_from_handle: (constructor)
  * @session: The session through which this object is accessed or created.
- * @object_handle: The raw CK_OBJECT_HANDLE of the object.
+ * @object_handle: The raw `CK_OBJECT_HANDLE` of the object.
  *
- * Initialize a GckObject from a raw PKCS\#11 handle. Normally you would use
- * gck_session_create_object() or gck_session_find_objects() to access objects.
+ * Initialize a GckObject from a raw PKCS#11 handle. Normally you would use
+ * [method@Session.create_object] or [method@Session.find_objects] to access
+ * objects.
  *
- * Return value: (transfer full): The new GckObject. You should use
- *               g_object_unref() when done with this object.
+ * Return value: (transfer full): The new object
  **/
 GckObject *
 gck_object_from_handle (GckSession *session,
@@ -238,7 +231,7 @@ gck_object_from_handle (GckSession *session,
  * @object_handles: (array length=n_object_handles): The raw object handles.
  * @n_object_handles: The number of raw object handles.
  *
- * Initialize a list of GckObject from raw PKCS\#11 handles. The handles argument must contain
+ * Initialize a list of GckObject from raw PKCS#11 handles. The handles argument must contain
  * contiguous CK_OBJECT_HANDLE handles in an array.
  *
  * Returns: (transfer full) (element-type Gck.Object): The list of #GckObject
@@ -267,7 +260,7 @@ gck_objects_from_handle_array (GckSession *session,
  * @object2: (type Gck.Object): a pointer to the second #GckObject
  *
  * Checks equality of two objects. Two GckObject objects can point to the same
- * underlying PKCS\#11 object.
+ * underlying PKCS#11 object.
  *
  * Return value: %TRUE if object1 and object2 are equal.
  *               %FALSE if either is not a GckObject.
@@ -335,7 +328,7 @@ gck_object_hash (gconstpointer object)
  * gck_object_get_handle:
  * @self: The object.
  *
- * Get the raw PKCS\#11 handle of a GckObject.
+ * Get the raw PKCS#11 handle of a GckObject.
  *
  * Return value: the raw CK_OBJECT_HANDLE object handle
  **/
@@ -350,7 +343,7 @@ gck_object_get_handle (GckObject *self)
  * gck_object_get_module:
  * @self: The object.
  *
- * Get the PKCS\#11 module to which this object belongs.
+ * Get the PKCS#11 module to which this object belongs.
  *
  * Returns: (transfer full): the module, which should be unreffed after use
  **/
@@ -367,7 +360,7 @@ gck_object_get_module (GckObject *self)
  * gck_object_get_session:
  * @self: The object
  *
- * Get the PKCS\#11 session assigned to make calls on when operating
+ * Get the PKCS#11 session assigned to make calls on when operating
  * on this object.
  *
  * This will only return a session if it was set explitly on this
@@ -406,7 +399,7 @@ perform_destroy (Destroy *args)
  * @cancellable: Optional cancellable object, or %NULL to ignore.
  * @error: A location to return an error.
  *
- * Destroy a PKCS\#11 object, deleting it from storage or the session.
+ * Destroy a PKCS#11 object, deleting it from storage or the session.
  * This call may block for an indefinite period.
  *
  * Return value: Whether the call was successful or not.
@@ -431,7 +424,7 @@ gck_object_destroy (GckObject *self, GCancellable *cancellable, GError **error)
  * @callback: Callback which is called when operation completes.
  * @user_data: Data to pass to the callback.
  *
- * Destroy a PKCS\#11 object, deleting it from storage or the session.
+ * Destroy a PKCS#11 object, deleting it from storage or the session.
  * This call will return immediately and complete asynchronously.
  **/
 void
@@ -457,7 +450,7 @@ gck_object_destroy_async (GckObject *self, GCancellable *cancellable,
  * @result: The result of the destory operation passed to the callback.
  * @error: A location to store an error.
  *
- * Get the status of the operation to destroy a PKCS\#11 object, begun with
+ * Get the status of the operation to destroy a PKCS#11 object, begun with
  * gck_object_destroy_async().
  *
  * Return value: Whether the object was destroyed successfully or not.
@@ -508,7 +501,7 @@ free_set_attributes (SetAttributes *args)
  * @cancellable: Optional cancellable object, or %NULL to ignore.
  * @error: A location to return an error.
  *
- * Set PKCS\#11 attributes on an object. This call may block for an indefinite period.
+ * Set PKCS#11 attributes on an object. This call may block for an indefinite period.
  *
  * If the @attrs #GckAttributes is floating, it is consumed.
  *
@@ -546,7 +539,7 @@ gck_object_set (GckObject *self, GckAttributes *attrs,
  * @callback: Callback which is called when operation completes.
  * @user_data: Data to pass to the callback.
  *
- * Set PKCS\#11 attributes on an object. This call will return
+ * Set PKCS#11 attributes on an object. This call will return
  * immediately and completes asynchronously.
  *
  * If the @attrs #GckAttributes is floating, it is consumed.
@@ -577,7 +570,7 @@ gck_object_set_async (GckObject *self, GckAttributes *attrs, GCancellable *cance
  * @result: The result of the destory operation passed to the callback.
  * @error: A location to store an error.
  *
- * Get the status of the operation to set attributes on a PKCS\#11 object,
+ * Get the status of the operation to set attributes on a PKCS#11 object,
  * begun with gck_object_set_async().
  *
  * Return value: Whether the attributes were successfully set on the object or not.
@@ -658,7 +651,7 @@ free_get_attributes (GetAttributes *args)
  * Get the specified attributes from the object. This call may
  * block for an indefinite period.
  *
- * Returns: (transfer full): the resulting PKCS\#11 attributes, or %NULL if an
+ * Returns: (transfer full): the resulting PKCS#11 attributes, or %NULL if an
  *          error occurred; the result must be unreffed when you're finished
  *          with it
  **/
@@ -882,7 +875,7 @@ free_get_attribute_data (GetAttributeData *args)
  *
  * This call may block for an indefinite period.
  *
- * Returns: (transfer full) (array length=n_data): the resulting PKCS\#11
+ * Returns: (transfer full) (array length=n_data): the resulting PKCS#11
  *          attribute data, or %NULL if an error occurred
  **/
 guchar *
@@ -913,7 +906,7 @@ gck_object_get_data (GckObject *self,
  *
  * This call may block for an indefinite period.
  *
- * Returns: (transfer full) (array length=n_data): The resulting PKCS\#11
+ * Returns: (transfer full) (array length=n_data): The resulting PKCS#11
  *          attribute data, or %NULL if an error occurred.
  **/
 guchar *
@@ -996,7 +989,7 @@ gck_object_get_data_async (GckObject *self, gulong attr_type, GckAllocator alloc
  * an object. For convenience the returned data has an extra null terminator,
  * not included in the returned length.
  *
- * Returns: (transfer full) (array length=n_data): The PKCS\#11 attribute data
+ * Returns: (transfer full) (array length=n_data): The PKCS#11 attribute data
  *          or %NULL if an error occurred.
  **/
 guchar *
@@ -1236,7 +1229,7 @@ free_get_template (get_template_args *args)
  *
  * This call may block for an indefinite period.
  *
- * Returns: (transfer full): the resulting PKCS\#11 attribute template, or %NULL
+ * Returns: (transfer full): the resulting PKCS#11 attribute template, or %NULL
  *          if an error occurred
  **/
 GckAttributes *
@@ -1268,19 +1261,19 @@ gck_object_get_template (GckObject *self, gulong attr_type,
  * gck_object_get_template_async:
  * @self: The object to get an attribute template from.
  * @attr_type: The template attribute type.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to be passed to the callback.
  *
- * Get an attribute template from the object. The attr_type must be for
+ * Get an attribute template from the object. The @attr_type must be for
  * an attribute which returns a template.
  *
  * This call will return immediately and complete asynchronously.
  **/
 void
 gck_object_get_template_async (GckObject *self, gulong attr_type,
-                                GCancellable *cancellable, GAsyncReadyCallback callback,
-                                gpointer user_data)
+                               GCancellable *cancellable, GAsyncReadyCallback callback,
+                               gpointer user_data)
 {
        GckCall *call;
        get_template_args *args;
@@ -1306,7 +1299,7 @@ gck_object_get_template_async (GckObject *self, gulong attr_type,
  * Get the result of an operation to get attribute template from
  * an object.
  *
- * Returns: (transfer full): the resulting PKCS\#11 attribute template, or %NULL
+ * Returns: (transfer full): the resulting PKCS#11 attribute template, or %NULL
  *          if an error occurred
  **/
 GckAttributes *
diff --git a/gck/gck-password.c b/gck/gck-password.c
index 717c5ca..13bb8f9 100644
--- a/gck/gck-password.c
+++ b/gck/gck-password.c
@@ -29,29 +29,23 @@
 
 #include <string.h>
 
-/**
- * SECTION:gck-password
- * @title: GckPassword
- * @short_description: Represents a password hich is requested of the user
- *
- * This is used in conjuction with GTlsInteraction. #GckPassword is a
- * GTlsPassword which contains additional information about which PKCS\#11
- * token or key the password is being requested for.
- */
-
 /**
  * GckPassword:
  *
- * A #GTlsPasswordClass that contains information about the PKCS\#11 token
- * or key the password is being requested for.
+ * Represents a password which is requested of the user.
+ *
+ * This is used in conjuction with [class@Gio.TlsInteraction]. `GckPassword` is
+ * a [class@Gio.TlsPassword] which contains additional information about which
+ * PKCS#11 token or key the password is being requested for.
  */
 
 /**
  * GckPasswordClass:
  * @parent: parent class
  *
- * The class for #GTlsPassword.
+ * The class struct for [class@Password].
  */
+
 enum {
        PROP_0,
        PROP_MODULE,
@@ -164,7 +158,7 @@ gck_password_class_init (GckPasswordClass *klass)
        /**
         * GckPassword:module:
         *
-        * The PKCS\#11 module that is requesting the password
+        * The PKCS#11 module that is requesting the password
         */
        g_object_class_install_property (gobject_class, PROP_MODULE,
                g_param_spec_object ("module", "Module", "PKCS11 Module",
@@ -173,7 +167,7 @@ gck_password_class_init (GckPasswordClass *klass)
        /**
         * GckPassword:token:
         *
-        * The PKCS\#11 token the password is for, if this is set then
+        * The PKCS#11 token the password is for, if this is set then
         * the GckPassword:object property will be %NULL
         */
        g_object_class_install_property (gobject_class, PROP_TOKEN,
@@ -183,7 +177,7 @@ gck_password_class_init (GckPasswordClass *klass)
        /**
         * GckPassword:key:
         *
-        * The PKCS\#11 key that the password is being requested for. If this
+        * The PKCS#11 key that the password is being requested for. If this
         * is set then the GckPassword:token property will be %NULL
         */
        g_object_class_install_property (gobject_class, PROP_KEY,
@@ -195,7 +189,7 @@ gck_password_class_init (GckPasswordClass *klass)
  * gck_password_get_module:
  * @self: the password object
  *
- * Get the PKCS\#11 module that is requesting the password.
+ * Get the PKCS#11 module that is requesting the password.
  *
  * Returns: (transfer full): the module that is requesting the password, which
  *          must be unreferenced after use
@@ -214,7 +208,7 @@ gck_password_get_module (GckPassword *self)
  * gck_password_get_token:
  * @self: the password object
  *
- * If the password request is to unlock a PKCS\#11 token, then this is the
+ * If the password request is to unlock a PKCS#11 token, then this is the
  * slot containing that token.
  *
  * Returns: (transfer full): the slot that contains the token, or %NULL if not
@@ -234,7 +228,7 @@ gck_password_get_token (GckPassword *self)
  * gck_password_get_key:
  * @self: the password object
  *
- * If the password request is to unlock a PKCS\#11 key, then this is the
+ * If the password request is to unlock a PKCS#11 key, then this is the
  * the object representing that key.
  *
  * Returns: (transfer full): the password is for this key, or %NULL if not
diff --git a/gck/gck-session.c b/gck/gck-session.c
index 99f7cdd..4c5fe08 100644
--- a/gck/gck-session.c
+++ b/gck/gck-session.c
@@ -1,4 +1,3 @@
-/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /* gck-session.h - the GObject PKCS#11 wrapper library
 
    Copyright (C) 2008, Stefan Walter
@@ -31,19 +30,13 @@
 
 #include <glib/gi18n-lib.h>
 
-/**
- * SECTION:gck-session
- * @title: GckSession
- * @short_description: Represents an open PKCS11 session.
- *
- * Before performing any PKCS11 operations, a session must be opened. This is
- * analogous to an open database handle, or a file handle.
- */
-
 /**
  * GckSession:
  *
  * Represents an open PKCS11 session.
+ *
+ * Before performing any PKCS11 operations, a session must be opened. This is
+ * analogous to an open database handle, or a file handle.
  */
 
 /**
@@ -335,7 +328,7 @@ gck_session_class_init (GckSessionClass *klass)
        /**
         * GckSession:opening-flags:
         *
-        * Raw PKCS\#11 flags used to open the PKCS\#11 session.
+        * Raw PKCS#11 flags used to open the PKCS#11 session.
         */
        g_object_class_install_property (gobject_class, PROP_OPENING_FLAGS,
                g_param_spec_ulong ("opening-flags", "Opening flags", "PKCS#11 open session flags",
@@ -345,7 +338,7 @@ gck_session_class_init (GckSessionClass *klass)
        /**
         * GckSession:app-data:
         *
-        * Raw PKCS\#11 application data used to open the PKCS\#11 session.
+        * Raw PKCS#11 application data used to open the PKCS#11 session.
         */
        g_object_class_install_property (gobject_class, PROP_APP_DATA,
                g_param_spec_pointer ("app-data", "App data", "PKCS#11 application data",
@@ -587,11 +580,11 @@ gck_session_info_free (GckSessionInfo *session_info)
 /**
  * gck_session_from_handle:
  * @slot: The slot which the session belongs to.
- * @session_handle: the raw PKCS\#11 handle of the session
+ * @session_handle: the raw PKCS#11 handle of the session
  * @options: Session options. Those which are used during opening a session have no effect.
  *
- * Initialize a GckSession object from a raw PKCS\#11 session handle.
- * Usually one would use the gck_slot_open_session() function to
+ * Initialize a session object from a raw PKCS#11 session handle.
+ * Usually one would use the [method@Slot.open_session] function to
  * create a session.
  *
  * Returns: (transfer full): the new GckSession object
@@ -618,7 +611,7 @@ gck_session_from_handle (GckSlot *slot,
  * gck_session_get_handle:
  * @self: The session object.
  *
- * Get the raw PKCS\#11 session handle from a GckSession object.
+ * Get the raw PKCS#11 session handle from a session object.
  *
  * Return value: The raw session handle.
  **/
@@ -633,7 +626,7 @@ gck_session_get_handle (GckSession *self)
  * gck_session_get_module:
  * @self: The session object.
  *
- * Get the PKCS\#11 module to which this session belongs.
+ * Get the PKCS#11 module to which this session belongs.
  *
  * Returns: (transfer full): the module, which should be unreffed after use
  **/
@@ -648,7 +641,7 @@ gck_session_get_module (GckSession *self)
  * gck_session_get_slot:
  * @self: The session object.
  *
- * Get the PKCS\#11 slot to which this session belongs.
+ * Get the PKCS#11 slot to which this session belongs.
  *
  * Return value: (transfer full): The slot, which should be unreffed after use.
  **/
@@ -709,7 +702,7 @@ gck_session_get_info (GckSession *self)
  * gck_session_get_state:
  * @self: the session
  *
- * Get the session state. The state is the various PKCS\#11 CKS_XXX flags.
+ * Get the session state. The state is the various PKCS#11 CKS_XXX flags.
  *
  * Returns: the session state
  */
@@ -812,7 +805,7 @@ gck_session_set_interaction (GckSession *self,
  * @slot: the slot to open session on
  * @options: session options
  * @interaction: (nullable): optional interaction for logins or object authentication
- * @cancellable: optional cancellation object
+ * @cancellable: (nullable): optional cancellation object
  * @error: location to place error or %NULL
  *
  * Open a session on the slot. This call may block for an indefinite period.
@@ -915,11 +908,11 @@ perform_init_pin (InitPin *args)
  * @pin: (nullable) (array length=n_pin): the user's PIN, or %NULL for
  *       protected authentication path
  * @n_pin: the length of the PIN
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error.
  *
  * Initialize the user's pin on this slot that this session is opened on.
- * According to the PKCS\#11 standards, the session must be logged in with
+ * According to the PKCS#11 standards, the session must be logged in with
  * the CKU_SO user type.
  *
  * This call may block for an indefinite period.
@@ -940,13 +933,13 @@ gck_session_init_pin (GckSession *self, const guchar *pin, gsize n_pin,
  * @self: Initialize PIN for this session's slot.
  * @pin: (nullable) (array length=n_pin): the user's PIN, or %NULL for protected authentication path
  * @n_pin: the length of the PIN
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
  *
  * Initialize the user's pin on this slot that this session is opened on.
- * According to the PKCS\#11 standards, the session must be logged in with
- * the CKU_SO user type.
+ * According to the PKCS#11 standards, the session must be logged in with
+ * the `CKU_SO` user type.
  *
  * This call will return immediately and completes asynchronously.
  **/
@@ -1020,7 +1013,7 @@ perform_set_pin (SetPin *args)
  * @new_pin: (nullable) (array length=n_new_pin): the user's new PIN, or %NULL
  *           for protected authentication path
  * @n_new_pin: The length of the PIN.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error.
  *
  * Change the user's pin on this slot that this session is opened on.
@@ -1047,7 +1040,7 @@ gck_session_set_pin (GckSession *self, const guchar *old_pin, gsize n_old_pin,
  * @new_pin: (nullable) (array length=n_new_pin): the user's new PIN, or %NULL
  *           for protected authentication path
  * @n_new_pin: the length of the new PIN
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
  *
@@ -1123,7 +1116,7 @@ perform_login (Login *args)
  * @pin: (nullable) (array length=n_pin): the user's PIN, or %NULL for
  *       protected authentication path
  * @n_pin: The length of the PIN.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error.
  *
  * Login the user on the session. This call may block for
@@ -1147,7 +1140,7 @@ gck_session_login (GckSession *self, gulong user_type, const guchar *pin,
  * @pin: (nullable) (array length=n_pin): the user's PIN, or %NULL for
  *       protected authentication path
  * @n_pin: The length of the PIN.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
  *
@@ -1216,7 +1209,7 @@ perform_interactive (Interactive *args)
  * @self: session to use for login
  * @user_type: the type of login user
  * @interaction: (nullable): interaction to request PIN when necessary
- * @cancellable: optional cancellation object, or %NULL
+ * @cancellable: (nullable): optional cancellation object, or %NULL
  * @error: location to return an error
  *
  * Login the user on the session requesting the password interactively
@@ -1251,7 +1244,7 @@ gck_session_login_interactive (GckSession *self,
  * @self: session to use for login
  * @user_type: the type of login user
  * @interaction: (nullable): interaction to request PIN when necessary
- * @cancellable: optional cancellation object, or %NULL
+ * @cancellable: (nullable): optional cancellation object, or %NULL
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
@@ -1317,7 +1310,7 @@ perform_logout (GckArguments *args)
 /**
  * gck_session_logout:
  * @self: Logout of this session.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error.
  *
  * Log out of the session. This call may block for an indefinite period.
@@ -1368,8 +1361,6 @@ gck_session_logout_finish (GckSession *self, GAsyncResult *result, GError **erro
 }
 
 
-
-
 /* CREATE OBJECT */
 
 typedef struct _CreateObject {
@@ -1413,10 +1404,10 @@ perform_create_object (CreateObject *args)
  * gck_session_create_object:
  * @self: The session to create the object on.
  * @attrs: The attributes to create the object with.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error, or %NULL.
  *
- * Create a new PKCS\#11 object. This call may block for an
+ * Create a new PKCS#11 object. This call may block for an
  * indefinite period.
  *
  * If the @attrs #GckAttributes is floating, it is consumed.
@@ -1447,14 +1438,14 @@ gck_session_create_object (GckSession *self, GckAttributes *attrs,
  * gck_session_create_object_async:
  * @self: The session to create the object on.
  * @attrs: The attributes to create the object with.
- * @cancellable: Optional cancellation object or %NULL.
+ * @cancellable: (nullable): Optional cancellation object or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
  *
- * Create a new PKCS\#11 object. This call will return immediately
+ * Create a new PKCS#11 object. This call will return immediately
  * and complete asynchronously.
  *
- * If the @attrs #GckAttributes is floating, it is consumed.
+ * If @attrs is a floating reference, it is consumed.
  **/
 void
 gck_session_create_object_async (GckSession *self, GckAttributes *attrs,
@@ -1481,7 +1472,7 @@ gck_session_create_object_async (GckSession *self, GckAttributes *attrs,
  * @result: The result passed to the callback.
  * @error: A location to return an error, or %NULL.
  *
- * Get the result of creating a new PKCS\#11 object.
+ * Get the result of creating a new PKCS#11 object.
  *
  * Return value: (transfer full): the newly created object or %NULL if an error occurred
  **/
@@ -1498,7 +1489,6 @@ gck_session_create_object_finish (GckSession *self, GAsyncResult *result, GError
 }
 
 
-
 /* FIND OBJECTS */
 
 typedef struct _FindObjects {
@@ -1581,14 +1571,14 @@ perform_find_objects (FindObjects *args)
  * gck_session_find_handles:
  * @self: the session to find objects on
  * @match: the attributes to match against objects
- * @cancellable: optional cancellation object or %NULL
+ * @cancellable: (nullable): optional cancellation object or %NULL
  * @n_handles: location to return number of handles
  * @error: a location to return an error or %NULL
  *
  * Find the objects matching the passed attributes. This call may
  * block for an indefinite period.
  *
- * If the @match #GckAttributes is floating, it is consumed.
+ * If @match is a floating reference, it is consumed.
  *
  * Returns: (transfer full) (array length=n_handles) (nullable): a list of
  *          the matching objects, which may be empty
@@ -1625,14 +1615,14 @@ gck_session_find_handles (GckSession *self,
  * gck_session_find_handles_async:
  * @self: the session to find objects on
  * @match: the attributes to match against the objects
- * @cancellable: optional cancellation object or %NULL
+ * @cancellable: (nullable): optional cancellation object or %NULL
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *
  * Find the objects matching the passed attributes. This call will
  * return immediately and complete asynchronously.
  *
- * If the @match #GckAttributes is floating, it is consumed.
+ * If @match is a floating reference, it is consumed.
  **/
 void
 gck_session_find_handles_async (GckSession *self,
@@ -1694,13 +1684,13 @@ gck_session_find_handles_finish (GckSession *self,
  * gck_session_find_objects:
  * @self: The session to find objects on.
  * @match: the attributes to match
- * @cancellable: Optional cancellation object or %NULL.
+ * @cancellable: (nullable): Optional cancellation object or %NULL.
  * @error: A location to return an error or %NULL.
  *
  * Find the objects matching the passed attributes. This call may
  * block for an indefinite period.
  *
- * If the @match #GckAttributes is floating, it is consumed.
+ * If @match is a floating reference, it is consumed.
  *
  * Returns: (transfer full) (element-type Gck.Object): a list of the matching
  *          objects, which may be empty
@@ -1733,7 +1723,7 @@ gck_session_find_objects (GckSession *self,
  * gck_session_find_objects_async:
  * @self: The session to find objects on.
  * @match: The attributes to match.
- * @cancellable: Optional cancellation object or %NULL.
+ * @cancellable: (nullable): Optional cancellation object or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
  *
@@ -1796,7 +1786,7 @@ gck_session_find_objects_finish (GckSession *self,
  *
  * Setup an enumerator for listing matching objects available via this session.
  *
- * If the @match #GckAttributes is floating, it is consumed.
+ * If @match is a floating reference, it is consumed.
  *
  * This call will not block but will return an enumerator immediately.
  *
@@ -1864,13 +1854,13 @@ perform_generate_key_pair (GenerateKeyPair *args)
  * @private_attrs: Additional attributes for the generated private key.
  * @public_key: (optional) (out): location to return the resulting public key
  * @private_key: (optional) (out): location to return the resulting private key.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error, or %NULL.
  *
- * Generate a new key pair of public and private keys. This call may block for an
- * indefinite period.
+ * Generate a new key pair of public and private keys. This call may block for
+ * an indefinite period.
  *
- * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is
+ * If @public_attrs and/or @private_attrs is a floating reference, it is
  * consumed.
  *
  * Return value: %TRUE if the operation succeeded.
@@ -1893,13 +1883,13 @@ gck_session_generate_key_pair (GckSession *self, gulong mech_type,
  * @private_attrs: Additional attributes for the generated private key.
  * @public_key: (optional) (out): a location to return the resulting public key
  * @private_key: (optional) (out): a location to return the resulting private key
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error, or %NULL.
  *
  * Generate a new key pair of public and private keys. This call may block for an
  * indefinite period.
  *
- * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is
+ * If @public_attrs and/or @private_attrs is a floating reference, it is
  * consumed.
  *
  * Return value: %TRUE if the operation succeeded.
@@ -1949,14 +1939,14 @@ gck_session_generate_key_pair_full (GckSession *self,
  * @mechanism: The mechanism to use for key generation.
  * @public_attrs: Additional attributes for the generated public key.
  * @private_attrs: Additional attributes for the generated private key.
- * @cancellable: Optional cancellation object or %NULL.
+ * @cancellable: (nullable): Optional cancellation object or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
  *
  * Generate a new key pair of public and private keys. This call will
  * return immediately and complete asynchronously.
  *
- * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is
+ * If @public_attrs and/or @private_attrs is a floating reference, it is
  * consumed.
  **/
 void
@@ -2073,7 +2063,7 @@ perform_wrap_key (WrapKey *args)
  * @mech_type: The mechanism type to use for wrapping.
  * @wrapped: The key to wrap.
  * @n_result: A location in which to return the length of the wrapped data.
- * @cancellable: A #GCancellable or %NULL
+ * @cancellable: (nullable): A #GCancellable or %NULL
  * @error: A location to return an error, or %NULL.
  *
  * Wrap a key into a byte stream. This call may block for an
@@ -2097,7 +2087,7 @@ gck_session_wrap_key (GckSession *self, GckObject *key, gulong mech_type,
  * @mechanism: The mechanism to use for wrapping.
  * @wrapped: The key to wrap.
  * @n_result: A location in which to return the length of the wrapped data.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error, or %NULL.
  *
  * Wrap a key into a byte stream. This call may block for an
@@ -2143,7 +2133,7 @@ gck_session_wrap_key_full (GckSession *self, GckObject *wrapper, GckMechanism *m
  * @wrapper: The key to use for wrapping.
  * @mechanism: The mechanism to use for wrapping.
  * @wrapped: The key to wrap.
- * @cancellable: Optional cancellation object or %NULL.
+ * @cancellable: (nullable): Optional cancellation object or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
  *
@@ -2259,13 +2249,13 @@ perform_unwrap_key (UnwrapKey *args)
  * @input: (array length=n_input): the wrapped data as a byte stream
  * @n_input: The length of the wrapped data.
  * @attrs: Additional attributes for the unwrapped key.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error, or %NULL.
  *
  * Unwrap a key from a byte stream. This call may block for an
  * indefinite period.
  *
- * If the @attrs #GckAttributes is floating, it is consumed.
+ * If @attrs is a floating reference, it is consumed.
  *
  * Returns: (transfer full): the new unwrapped key or %NULL if the
  *          operation failed
@@ -2292,13 +2282,13 @@ gck_session_unwrap_key (GckSession *self,
  * @input: (array length=n_input): the wrapped data as a byte stream
  * @n_input: The length of the wrapped data.
  * @attrs: Additional attributes for the unwrapped key.
- * @cancellable: Optional cancellation object, or %NULL.
+ * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @error: A location to return an error, or %NULL.
  *
  * Unwrap a key from a byte stream. This call may block for an
  * indefinite period.
  *
- * If the @attrs #GckAttributes is floating, it is consumed.
+ * If @attrs is a floating reference, it is consumed.
  *
  * Returns: (transfer full): the new unwrapped key or %NULL if the operation
  *          failed
@@ -2347,14 +2337,14 @@ gck_session_unwrap_key_full (GckSession *self,
  * @input: (array length=n_input): the wrapped data as a byte stream
  * @n_input: The length of the wrapped data.
  * @attrs: Additional attributes for the unwrapped key.
- * @cancellable: Optional cancellation object or %NULL.
+ * @cancellable: (nullable): Optional cancellation object or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
  *
  * Unwrap a key from a byte stream. This call will
  * return immediately and complete asynchronously.
  *
- * If the @attrs #GckAttributes is floating, it is consumed.
+ * If @attrs is a floating reference, it is consumed.
  **/
 void
 gck_session_unwrap_key_async (GckSession *self,
diff --git a/gck/gck-slot.c b/gck/gck-slot.c
index 435fe61..8ec121e 100644
--- a/gck/gck-slot.c
+++ b/gck/gck-slot.c
@@ -30,19 +30,14 @@
 #include <string.h>
 #include <time.h>
 
-/**
- * SECTION:gck-slot
- * @title: GckSlot
- * @short_description: Represents a PKCS\#11 slot that can contain a token.
- *
- * A PKCS11 slot can contain a token. As an example, a slot might be a card reader, and the token
- * the card. If the PKCS\#11 module is not a hardware driver, often the slot and token are equivalent.
- */
-
 /**
  * GckSlot:
  *
- * Represents a PKCS11 slot.
+ * Represents a PKCS#11 slot that can contain a token.
+ *
+ * A PKCS#11 slot can contain a token. As an example, a slot might be a card
+ * reader, and the token the card. If the PKCS#11 module is not a hardware
+ * driver, often the slot and token are equivalent.
  */
 
 enum {
@@ -421,7 +416,7 @@ gck_mechanisms_check (GArray *mechanisms, ...)
  * @slot2: (type Gck.Slot): a pointer to the second #GckSlot
  *
  * Checks equality of two slots. Two GckSlot objects can point to the same
- * underlying PKCS\#11 slot.
+ * underlying PKCS#11 slot.
  *
  * Return value: %TRUE if slot1 and slot2 are equal.
  *               %FALSE if either is not a GckSlot.
@@ -470,9 +465,9 @@ gck_slot_hash (gconstpointer slot)
 /**
  * gck_slot_from_handle:
  * @module: The module that this slot is on.
- * @slot_id: The raw PKCS\#11 handle or slot id of this slot.
+ * @slot_id: The raw PKCS#11 handle or slot id of this slot.
  *
- * Create a new GckSlot object for a raw PKCS\#11 handle.
+ * Create a new GckSlot object for a raw PKCS#11 handle.
  *
  * Returns: (transfer full): The new GckSlot object.
  **/
@@ -490,7 +485,7 @@ gck_slot_from_handle (GckModule *module,
  * gck_slot_get_handle:
  * @self: The slot to get the handle of.
  *
- * Get the raw PKCS\#11 handle of a slot.
+ * Get the raw PKCS#11 handle of a slot.
  *
  * Return value: the raw CK_SLOT_ID handle
  **/
@@ -979,9 +974,9 @@ gck_slot_open_session (GckSlot *self,
  * gck_slot_open_session_full: (skip)
  * @self: The slot to open a session on.
  * @options: The options to open the new session with.
- * @pkcs11_flags: Additional raw PKCS\#11 flags.
+ * @pkcs11_flags: Additional raw PKCS#11 flags.
  * @app_data: Application data for notification callback.
- * @notify: PKCS\#11 notification callback.
+ * @notify: PKCS#11 notification callback.
  * @cancellable: Optional cancellation object, or %NULL.
  * @error: A location to return an error, or %NULL.
  *
@@ -1054,9 +1049,9 @@ on_open_session_complete (GObject *source,
  * gck_slot_open_session_full_async: (skip)
  * @self: The slot to open a session on.
  * @options: Options to open the new session with.
- * @pkcs11_flags: Additional raw PKCS\#11 flags.
+ * @pkcs11_flags: Additional raw PKCS#11 flags.
  * @app_data: Application data for notification callback.
- * @notify: PKCS\#11 notification callback.
+ * @notify: PKCS#11 notification callback.
  * @cancellable: (nullable): Optional cancellation object, or %NULL.
  * @callback: Called when the operation completes.
  * @user_data: Data to pass to the callback.
@@ -1122,7 +1117,7 @@ gck_slot_open_session_finish (GckSlot *self, GAsyncResult *result, GError **erro
  * @self: the slot to match
  * @uri: the uri to match against the slot
  *
- * Check whether the PKCS\#11 URI matches the slot
+ * Check whether the PKCS#11 URI matches the slot
  *
  * Returns: whether the URI matches or not
  */
diff --git a/gck/gck-uri.c b/gck/gck-uri.c
index 7187042..bd524a4 100644
--- a/gck/gck-uri.c
+++ b/gck/gck-uri.c
@@ -34,39 +34,17 @@
 #include <string.h>
 #include <stdlib.h>
 
-/**
- * SECTION:gck-uri
- * @title: PKCS11 URIs
- * @short_description: Parsing and building PKCS\#11 URIs.
- *
- * <ulink href='http://tools.ietf.org/html/draft-pechanec-pkcs11uri-03'>PKCS\#11 URIs</ulink>
- * are a standard for referring to PKCS\#11 modules, tokens, or objects. What the
- * PKCS\#11 URI refers to depends on the context in which it is used.
- *
- * A PKCS\#11 URI can always resolve to more than one object, token or module. A
- * PKCS\#11 URI that refers to a token, would (when used in a context that expects
- * objects) refer to all the token on that module.
- *
- * In most cases the parsing or building of URIs is handled elsewhere in the GCK
- * library. For example to enumerate objects that match a PKCS\#11 URI use the
- * gck_modules_enumerate_uri() function.
- *
- * To parse a PKCS\#11 URI use the gck_uri_parse() function passing in the type of
- * context in which you're using the URI. To build a URI use the gck_uri_build()
- * function.
- **/
-
 /**
  * GckUriData:
- * @any_unrecognized: whether any parts of the PKCS\#11 URI were unsupported or unrecognized.
- * @module_info: information about the PKCS\#11 modules matching the URI.
- * @token_info: information about the PKCS\#11 tokens matching the URI.
- * @attributes: information about the PKCS\#11 objects matching the URI.
+ * @any_unrecognized: whether any parts of the PKCS#11 URI were unsupported or unrecognized.
+ * @module_info: information about the PKCS#11 modules matching the URI.
+ * @token_info: information about the PKCS#11 tokens matching the URI.
+ * @attributes: information about the PKCS#11 objects matching the URI.
  *
- * Information about the contents of a PKCS\#11 URI. Various fields may be %NULL
+ * Information about the contents of a PKCS#11 URI. Various fields may be %NULL
  * depending on the context that the URI was parsed for.
  *
- * Since PKCS\#11 URIs represent a set which results from the intersections of
+ * Since PKCS#11 URIs represent a set which results from the intersections of
  * all of the URI parts, if @any_recognized is set to %TRUE then usually the URI
  * should be treated as not matching anything.
  */
@@ -79,7 +57,7 @@
  * @GCK_URI_WITH_VERSION: the URI has specific version numbers for module and/or token
  * @GCK_URI_FOR_ANY: parse all recognized components of the URI.
  *
- * Which parts of the PKCS\#11 URI will be parsed or formatted. These can be
+ * Which parts of the PKCS#11 URI will be parsed or formatted. These can be
  * combined.
  */
 
@@ -109,7 +87,7 @@
  * @GCK_URI_BAD_VERSION: bad URI version component
  * @GCK_URI_NOT_FOUND: piece of the URI was not found
  *
- * Various error codes used with PKCS\#11 URIs
+ * Various error codes used with PKCS#11 URIs
  */
 
 /**
@@ -186,7 +164,7 @@ gck_uri_data_new (void)
  * @flags: the context in which the URI will be used.
  * @error: a #GError, or %NULL.
  *
- * Parse a PKCS\#11 URI for use in a given context.
+ * Parse a PKCS#11 URI for use in a given context.
  *
  * The result will contain the fields that are relevant for
  * the given context. See #GckUriData  for more info.
@@ -266,10 +244,10 @@ gck_uri_parse (const gchar *string, GckUriFlags flags, GError **error)
  * @uri_data: the info to build the URI from.
  * @flags: The context that the URI is for
  *
- * Build a PKCS\#11 URI. The various parts relevant to the flags
+ * Build a PKCS#11 URI. The various parts relevant to the flags
  * specified will be used to build the URI.
  *
- * Return value: a newly allocated string containing a PKCS\#11 URI.
+ * Return value: a newly allocated string containing a PKCS#11 URI.
  */
 gchar*
 gck_uri_build (GckUriData *uri_data, GckUriFlags flags)
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.
@@ -62,12 +61,6 @@
  * interface.
  */
 
-/**
- * GcrCertificate:
- *
- * An object which holds a certificate.
- */
-
 /**
  * GcrCertificateIface:
  * @parent: the parent interface type
@@ -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
@@ -21,23 +21,16 @@
 
 #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
@@ -23,22 +23,13 @@
 
 #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
@@ -23,19 +23,10 @@
 
 #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,29 +25,23 @@
 #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
  * the filter or not.
  */
 
-/**
- * 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
@@ -31,22 +31,6 @@
 
 #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
@@ -54,7 +38,13 @@
  * @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
@@ -36,31 +36,20 @@
 
 #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
@@ -31,22 +31,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
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
@@ -26,30 +26,14 @@
 
 #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
@@ -26,27 +26,14 @@
 
 #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
@@ -33,40 +33,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:
  *
@@ -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
@@ -27,27 +27,12 @@
 
 #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 {
diff --git a/meson.build b/meson.build
index 6fa0ff4..dea1b69 100644
--- a/meson.build
+++ b/meson.build
@@ -1,6 +1,6 @@
 project('gcr', 'c',
   version: '3.41.0',
-  meson_version: '>= 0.49',
+  meson_version: '>= 0.52',
   license: 'GPL2+',
 )
 
@@ -101,6 +101,10 @@ if get_option('gtk')
   subdir('ui')
 endif
 if get_option('gtk_doc')
+  if not get_option('introspection')
+    error('Can\'t generate docs without introspection enabled!')
+  endif
+
   subdir('docs')
 endif
 
diff --git a/ui/gcr-certificate-renderer.c b/ui/gcr-certificate-renderer.c
index 513cf01..70bfb5d 100644
--- a/ui/gcr-certificate-renderer.c
+++ b/ui/gcr-certificate-renderer.c
@@ -748,7 +748,7 @@ gcr_certificate_renderer_set_certificate (GcrCertificateRenderer *self, GcrCerti
  * gcr_certificate_renderer_get_attributes:
  * @self: The renderer
  *
- * Get the PKCS\#11 attributes, if any, set for this renderer to display.
+ * Get the PKCS#11 attributes, if any, set for this renderer to display.
  *
  * Returns: (nullable) (transfer none): the attributes, owned by the renderer
  *
@@ -766,8 +766,8 @@ gcr_certificate_renderer_get_attributes (GcrCertificateRenderer *self)
  * @self: The renderer
  * @attrs: (nullable): attributes to set
  *
- * Set the PKCS\#11 attributes for this renderer to display. One of the attributes
- * should be a CKA_VALUE type attribute containing a DER encoded certificate.
+ * Set the PKCS#11 attributes for this renderer to display. One of the attributes
+ * should be a `CKA_VALUE` type attribute containing a DER encoded certificate.
  *
  * Deprecated: 3.6: Use gcr_renderer_set_attributes() instead
  */
diff --git a/ui/gcr-certificate-request-renderer.c b/ui/gcr-certificate-request-renderer.c
index 2f3f44b..f239a9b 100644
--- a/ui/gcr-certificate-request-renderer.c
+++ b/ui/gcr-certificate-request-renderer.c
@@ -436,7 +436,7 @@ _gcr_certificate_request_renderer_iface (GcrRendererIface *iface)
  *
  * Create a new certificate request renderer to display the label and attributes.
  * One of the attributes should be a CKA_VALUE type attribute containing a DER
- * encoded PKCS\#10 certificate request or an SPKAC request.
+ * encoded PKCS#10 certificate request or an SPKAC request.
  *
  * Returns: (transfer full): a newly allocated #GcrCertificateRequestRenderer, which
  *          should be released with g_object_unref()
@@ -455,7 +455,7 @@ _gcr_certificate_request_renderer_new_for_attributes (const gchar *label,
  * gcr_certificate_request_renderer_get_attributes:
  * @self: the renderer
  *
- * Get the PKCS\#11 attributes, if any, set for this renderer to display.
+ * Get the PKCS#11 attributes, if any, set for this renderer to display.
  *
  * Returns: (nullable) (transfer none): the attributes, owned by the renderer
  */
@@ -471,8 +471,8 @@ _gcr_certificate_request_renderer_get_attributes (GcrCertificateRequestRenderer
  * @self: the renderer
  * @attrs: (nullable): attributes to set
  *
- * Set the PKCS\#11 attributes for this renderer to display. One of the attributes
- * should be a CKA_VALUE type attribute containing a DER encoded PKCS\#10
+ * Set the PKCS#11 attributes for this renderer to display. One of the attributes
+ * should be a `CKA_VALUE` type attribute containing a DER encoded PKCS#10
  * certificate request or an SPKAC request.
  */
 void
diff --git a/ui/gcr-certificate-widget.c b/ui/gcr-certificate-widget.c
index 9a71490..731ccee 100644
--- a/ui/gcr-certificate-widget.c
+++ b/ui/gcr-certificate-widget.c
@@ -31,31 +31,20 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-certificate-widget
- * @title: GcrCertificateWidget
- * @short_description: Certificate widget and renderer
+ * GcrCertificateWidget:
  *
- * A #GcrCertificateWidget can be used to display a certificate. The widget
- * is normally in a collapsed state showing only details, but can be expanded
- * by the user.
+ * A widget that can be used to display a certificate.
  *
- * Use gcr_certificate_widget_new() to create a new certificate widget. Only
- * one certificate can be displayed.  A #GcrCertificateWidget contains a
- * #GcrViewer internally and #GcrCertificateRenderer is used to render the
- * certificate to the viewer. To show more than one certificate in a view,
- * create the viewer and add renderers to it.
- */
-
-/**
- * GcrCertificateWidget:
+ * A certificate widget is normally in a collapsed state showing only
+ * details, but can be expanded by the user.
  *
- * A widget that displays a certificate.
- */
-
-/**
- * GcrCertificateWidgetClass:
+ * Use [ctor CertificateWidget new] to create a new certificate widget. Only
+ * one certificate can be displayed. It contains a [iface@Viewer] internally
+ * and [class@CertificateRenderer] is used to render the certificate to the
+ * viewer.
  *
- * The class for #GcrCertificateWidget
+ * To show more than one certificate in a view, create the viewer and
+ * add renderers to it.
  */
 
 enum {
@@ -186,8 +175,7 @@ gcr_certificate_widget_class_init (GcrCertificateWidgetClass *klass)
  *
  * Create a new certificate widget which displays a given certificate.
  *
- * Returns: (transfer full): a newly allocated #GcrCertificateWidget, which
- *          should be freed with g_object_unref()
+ * Returns: (transfer full): a new certificate widget
  */
 GcrCertificateWidget *
 gcr_certificate_widget_new (GcrCertificate *certificate)
diff --git a/ui/gcr-collection-model.c b/ui/gcr-collection-model.c
index dd70985..d3de1a4 100644
--- a/ui/gcr-collection-model.c
+++ b/ui/gcr-collection-model.c
@@ -32,34 +32,28 @@
 #include <unistd.h>
 
 /**
- * SECTION:gcr-collection-model
- * @title: GcrCollectionModel
- * @short_description: A GtkTreeModel that represents a collection
+ * GcrCollectionModel:
+ *
+ * Ain implementation of a [class@Gtk.TreeModel] which contains a row for each
+ * object in a [class@Gcr.Collection].
  *
- * This is an implementation of #GtkTreeModel which represents the objects in
- * the a #GcrCollection. As objects are added or removed from the collection,
- * rows are added and removed from this model.
+ * As objects are added or removed from the collection, rows are added and
+ * removed from this model.
  *
  * The row values come from the properties of the objects in the collection. Use
- * gcr_collection_model_new() to create a new collection model. To have more
- * control over the values use a set of #GcrColumn structures to define the
- * columns. This can be done with gcr_collection_model_new_full() or
- * gcr_collection_model_set_columns().
+ * [ctor CollectionModel new] to create a new collection model. To have more
+ * control over the values use a set of [struct@Gcr.Column] structures to
+ * define the columns. This can be done with [ctor@CollectionModel.new_full] or
+ * [method@CollectionModel.set_columns].
  *
  * Each row can have a selected state, which is represented by a boolean column.
  * The selected state can be toggled with gcr_collection_model_toggle_selected()
  * or set with gcr_collection_model_set_selected_objects() and retrieved with
- * gcr_collection_model_get_selected_objects().
+ * [method@CollectionModel.get_selected_objects].
  *
  * To determine which object a row represents and vice versa, use the
- * gcr_collection_model_iter_for_object() or gcr_collection_model_object_for_iter()
- * functions.
- */
-
-/**
- * GcrCollectionModel:
- *
- * A #GtkTreeModel which contains a row for each object in a #GcrCollection.
+ * [method@CollectionModel.iter_for_object] or
+ * [method@CollectionModel.object_for_iter] functions.
  */
 
 /**
@@ -74,8 +68,9 @@
  * @GCR_COLLECTION_MODEL_LIST: only objects in the top collection, no child objects
  * @GCR_COLLECTION_MODEL_TREE: show objects in the collection, and child objects in a tree form
  *
- * If set GcrCollectionModel is created with a mode of %GCR_COLLECTION_MODEL_TREE,
- * then any included objects that are themselves a #GcrCollection, will have all child
+ * If a [class@CollectionModel] is created with a mode of
+ * %GCR_COLLECTION_MODEL_TREE, then any included objects that are themselves a
+ * [class@Gcr.Collection], will have all child
  * objects include as child rows in a tree form.
  */
 
diff --git a/ui/gcr-combo-selector.c b/ui/gcr-combo-selector.c
index b08a80e..cac6419 100644
--- a/ui/gcr-combo-selector.c
+++ b/ui/gcr-combo-selector.c
@@ -28,25 +28,11 @@
 
 #include <string.h>
 
-/**
- * SECTION:gcr-combo-selector
- * @title: GcrComboSelector
- * @short_description: A selector widget to select a single certificate or key.
- *
- * The #GcrComboSelector can be used to select a certificate or key. It allows
- * the user to select one object from the selector at a time.
- */
-
 /**
  * GcrComboSelector:
  *
- * A combo selector widget.
- */
-
-/**
- * GcrComboSelectorClass:
- *
- * The class for #GcrComboSelector.
+ * A widget that can be used to select a certificate or key. It allows
+ * the user to select one object from the selector at a time.
  */
 
 enum {
@@ -61,10 +47,6 @@ struct _GcrComboSelectorPrivate {
 
 G_DEFINE_TYPE_WITH_PRIVATE (GcrComboSelector, gcr_combo_selector, GTK_TYPE_COMBO_BOX);
 
-/* -----------------------------------------------------------------------------
- * INTERNAL
- */
-
 /* -----------------------------------------------------------------------------
  * OBJECT
  */
diff --git a/ui/gcr-failure-renderer.c b/ui/gcr-failure-renderer.c
index 37f8c90..46ad600 100644
--- a/ui/gcr-failure-renderer.c
+++ b/ui/gcr-failure-renderer.c
@@ -27,6 +27,12 @@
 #include <gdk/gdk.h>
 #include <glib/gi18n-lib.h>
 
+/**
+ * GcrFailureRenderer:
+ *
+ * A renderer that can be used for unsupported data.
+ */
+
 enum {
        PROP_0,
        PROP_LABEL,
diff --git a/ui/gcr-import-button.c b/ui/gcr-import-button.c
index 56de3e7..f3a6478 100644
--- a/ui/gcr-import-button.c
+++ b/ui/gcr-import-button.c
@@ -38,20 +38,14 @@ enum {
        PROP_LABEL
 };
 
-/**
- * SECTION:gcr-import-button
- * @title: GcrImportButton
- * @short_description: Button which imports parsed certificates and keys
- *
- * A button which imports keys and certificates. Shows a spinner when the
- * button is activated. When more than one importer is available shows
- * a drop down to select which to import to.
- */
-
 /**
  * GcrImportButton:
  *
- * Button which imports parsed certificates and keys.
+ * A button which imports keys and certificates.
+ *
+ * The import button shows a spinner when the button is activated. When more
+ * than one importer is available, it shows a drop down to select which to
+ * import to.
  */
 
 /**
@@ -60,7 +54,7 @@ enum {
  * @importing: Emitted when the import begins.
  * @imported: Emitted when the import completes, or fails.
  *
- * Class for #GcrImportButton.
+ * Class struct for [class@ImportButton].
  */
 
 struct _GcrImportButtonPrivate {
diff --git a/ui/gcr-key-renderer.c b/ui/gcr-key-renderer.c
index c2fedcc..850a2ca 100644
--- a/ui/gcr-key-renderer.c
+++ b/ui/gcr-key-renderer.c
@@ -448,7 +448,7 @@ gcr_key_renderer_new (const gchar *label, GckAttributes *attrs)
  * @attrs: (nullable): the attributes to display
  *
  * Get the attributes displayed in the renderer. The attributes should represent
- * either an RSA, DSA, or EC key in PKCS\#11 style.
+ * either an RSA, DSA, or EC key in PKCS#11 style.
  */
 void
 gcr_key_renderer_set_attributes (GcrKeyRenderer *self, GckAttributes *attrs)
diff --git a/ui/gcr-key-widget.c b/ui/gcr-key-widget.c
index 26737ff..708671c 100644
--- a/ui/gcr-key-widget.c
+++ b/ui/gcr-key-widget.c
@@ -28,32 +28,20 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-key-widget
- * @title: GcrKeyWidget
- * @short_description: Key widget and renderer
+ * GcrKeyWidget:
  *
- * A #GcrKeyWidget can be used to display a RSA, DSA or EC key. The widget
- * is normally in a collapsed state showing only details, but can be expanded
- * by the user.
+ * A key widget and renderer
  *
- * Use gcr_key_widget_new() to create a new key widget. Only
- * one key can be displayed.  A #GcrKeyWidget contains a
- * #GcrViewer internally and #GcrKeyRenderer is used to render the
- * key to the viewer. To show more than one key in a view,
- * create the viewer and add renderers to it.
- */
-
-/**
- * GcrKeyWidget:
+ * A key widget can be used to display a RSA, DSA or EC key. The widget is
+ * normally in a collapsed state showing only details, but can be expanded by
+ * the user.
  *
- * A widget that displays a key.
+ * Use [ctor KeyWidget new] to create a new key widget. Only one key can be
+ * displayed. A key widget contains a [iface@Viewer] internally and
+ * [class@KeyRenderer] is used to render the key to the viewer. To show more
+ * than one key in a view, create the viewer and add renderers to it.
  */
 
-/**
- * GcrKeyWidgetClass:
- *
- * The class for #GcrKeyWidget
- */
 enum {
        PROP_0,
        PROP_ATTRIBUTES
@@ -197,7 +185,7 @@ gcr_key_widget_new (GckAttributes *attrs)
  * @attrs: (nullable): the attributes to display
  *
  * Get the attributes displayed in the widget. The attributes should represent
- * either an RSA, DSA or EC key in PKCS\#11 style.
+ * either an RSA, DSA or EC key in PKCS#11 style.
  */
 void
 gcr_key_widget_set_attributes (GcrKeyWidget *self, GckAttributes *attrs)
diff --git a/ui/gcr-list-selector.c b/ui/gcr-list-selector.c
index 7271cf0..9445c6a 100644
--- a/ui/gcr-list-selector.c
+++ b/ui/gcr-list-selector.c
@@ -33,25 +33,12 @@
 
 #include <string.h>
 
-/**
- * SECTION:gcr-list-selector
- * @title: GcrListSelector
- * @short_description: A selector widget to one or more certificates from a list.
- *
- * The #GcrListSelector can be used to select one or more certificates or keys.
- * Live search is available for quick filtering.
- */
-
 /**
  * GcrListSelector:
  *
- * A list selector widget.
- */
-
-/**
- * GcrListSelectorClass:
+ * A selector widget to select 1 or more certificates or keys from a list.
  *
- * The class for #GcrListSelector.
+ * Live search is available for quick filtering.
  */
 
 enum {
diff --git a/ui/gcr-prompt-dialog.c b/ui/gcr-prompt-dialog.c
index 5331b6e..80726ba 100644
--- a/ui/gcr-prompt-dialog.c
+++ b/ui/gcr-prompt-dialog.c
@@ -35,27 +35,12 @@
 #endif
 #include <glib/gi18n.h>
 
-/**
- * SECTION:gcr-prompt-dialog
- * @title: GcrPromptDialog
- * @short_description: a GTK+ dialog prompt
- *
- * A #GcrPrompt implementation which shows a GTK+ dialog. The dialog will
- * remain visible (but insensitive) between prompts. If the user cancels the
- * dialog between prompts, then the dialog will be hidden.
- */
-
 /**
  * GcrPromptDialog:
  *
- * A #GcrPrompt implementation which shows a GTK+ dialog.
- */
-
-/**
- * GcrPromptDialogClass:
- * @parent_class: parent class
- *
- * The class for #GcrPromptDialog.
+ * A [iface@Gcr.Prompt] implementation which shows a GTK dialog. The dialog
+ * will remain visible (but insensitive) between prompts. If the user cancels
+ * the dialog between prompts, then the dialog will be hidden.
  */
 
 #ifdef GCR_DISABLE_GRABS
diff --git a/ui/gcr-renderer.c b/ui/gcr-renderer.c
index 4f76793..727bf57 100644
--- a/ui/gcr-renderer.c
+++ b/ui/gcr-renderer.c
@@ -32,27 +32,20 @@
 #include <gtk/gtk.h>
 
 /**
- * SECTION:gcr-renderer
- * @title: GcrRenderer
- * @short_description: An interface implemented by renderers.
+ * GcrRenderer:
  *
- * A #GcrRenderer is an interface that's implemented by renderers which wish
- * to render data to a #GcrViewer.
+ * An interface that's implemented by renderers which wish to render data to a
+ * [class@Viewer].
  *
- * The interaction between #GcrRenderer and #GcrViewer is not stable yet, and
- * so new renderers cannot be implemented outside the Gcr library at this time.
+ * The interaction between [class@Renderer] and [class@Viewer] is not stable
+ * yet, and so new renderers cannot be implemented outside the Gcr library at
+ * this time.
  *
  * To lookup a renderer for a given set of attributes, use the gcr_renderer_create()
  * function. This will create and initialize a renderer that's capable of viewing
  * the data in those attributes.
  */
 
-/**
- * GcrRenderer:
- *
- * A renderer.
- */
-
 /**
  * GcrRendererIface:
  * @parent: the parent interface type
@@ -190,7 +183,7 @@ gcr_renderer_emit_data_changed (GcrRenderer *self)
  * gcr_renderer_get_attributes:
  * @self: The renderer
  *
- * Get the PKCS\#11 attributes, if any, set for this renderer to display.
+ * Get the PKCS#11 attributes, if any, set for this renderer to display.
  *
  * Returns: (nullable) (transfer none): the attributes, owned by the renderer
  */
@@ -212,7 +205,7 @@ gcr_renderer_get_attributes (GcrRenderer *self)
  * @self: The renderer
  * @attrs: (nullable): attributes to set
  *
- * Set the PKCS\#11 attributes for this renderer to display.
+ * Set the PKCS#11 attributes for this renderer to display.
  */
 void
 gcr_renderer_set_attributes (GcrRenderer *self,
diff --git a/ui/gcr-secure-entry-buffer.c b/ui/gcr-secure-entry-buffer.c
index 6642061..a209a22 100644
--- a/ui/gcr-secure-entry-buffer.c
+++ b/ui/gcr-secure-entry-buffer.c
@@ -1,4 +1,3 @@
-/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /* gcr-secure-buffer.c - secure memory gtkentry buffer
 
    Copyright (C) 2009 Stefan Walter
@@ -29,35 +28,23 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-secure-entry-buffer
- * @title: GcrSecureEntryBuffer
- * @short_description: a GtkEntryBuffer that uses non-pageable memory
+ * GcrSecureEntryBuffer:
+ *
+ * A [class@Gtk.EntryBuffer] that uses non-pageable memory.
  *
  * It's good practice to try to keep passwords or sensitive secrets out of
  * pageable memory whenever possible, so that they don't get written to disk.
  *
- * This is a #GtkEntryBuffer to be used with #GtkEntry which uses non-pageable
- * memory to store a password placed in the entry. In order to make any sense
- * at all, the entry must have it's visibility turned off, and just be displaying
- * place holder characters for the text. That is, a password style entry.
+ * A [class@SecureEntryBuffer] is a [class@Gtk.EntryBuffer] to be used with
+ * [class@Gtk.Entry] which uses non-pageable memory to store a password placed
+ * in the entry. In order to make any sense at all, the entry must have it's
+ * visibility turned off, and just be displaying place holder characters for
+ * the text. That is, a password style entry.
  *
- * Use gtk_entry_new_with_buffer() or gtk_entry_set_buffer() to set this buffer
+ * Use [ctor@Gtk.Entry.new_with_buffer] or [method@Gtk.Entry.set_buffer] to set this buffer
  * on an entry.
  */
 
-/**
- * GcrSecureEntryBuffer:
- *
- * A #GtkEntryBuffer which uses non-pageable memory for passwords or secrets.
- */
-
-/**
- * GcrSecureEntryBufferClass:
- * @parent_class: parent class
- *
- * The class for #GcrSecureEntryBuffer.
- */
-
 EGG_SECURE_DECLARE (secure_entry_buffer);
 
 /* Initial size of buffer, in bytes */
@@ -217,8 +204,7 @@ gcr_secure_entry_buffer_class_init (GcrSecureEntryBufferClass *klass)
 /**
  * gcr_secure_entry_buffer_new:
  *
- * Create a new #GcrSecureEntryBuffer, a #GtkEntryBuffer which uses
- * non-pageable memory for the text.
+ * Create a new secure entry buffer.
  *
  * Returns: (transfer full): the new entry buffer
  */
diff --git a/ui/gcr-tree-selector.c b/ui/gcr-tree-selector.c
index 3c0bbd0..e4db6ea 100644
--- a/ui/gcr-tree-selector.c
+++ b/ui/gcr-tree-selector.c
@@ -28,25 +28,11 @@
 
 #include <string.h>
 
-/**
- * SECTION:gcr-tree-selector
- * @title: GcrTreeSelector
- * @short_description: A selector widget to select certificates or keys.
- *
- * The #GcrTreeSelector can be used to select certificates or keys. It allows
- * the user to select multiple objects from a tree.
- */
-
 /**
  * GcrTreeSelector:
  *
- * A tree selector widget.
- */
-
-/**
- * GcrTreeSelectorClass:
- *
- * The class for #GcrTreeSelector.
+ * A tree selector can be used to select certificates or keys. It allows
+ * the user to select multiple objects from a tree.
  */
 
 enum {
diff --git a/ui/gcr-unlock-options-widget.c b/ui/gcr-unlock-options-widget.c
index afcc473..7db3257 100644
--- a/ui/gcr-unlock-options-widget.c
+++ b/ui/gcr-unlock-options-widget.c
@@ -22,17 +22,16 @@
 #include <glib/gi18n-lib.h>
 
 /**
- * SECTION:gcr-unlock-options-widget
- * @title: GcrUnlockOptionsWidget
- * @short_description: A widget for unlock options
+ * GcrUnlockOptionsWidget:
+ *
+ * This widget displays a set of unlock options for the user to select.
  *
- * This widget displays a set of unlock options for the user to select. The user
- * can choose between keeping caching the unlock indefinitely, or for a given
- * amount of time.
+ * The user can choose between keeping caching the unlock indefinitely, or for
+ * a given amount of time.
  *
  * Each option has a different name, for example #GCR_UNLOCK_OPTION_ALWAYS. These
  * names are used together with the various functions like
- * gcr_unlock_options_widget_get_choice().
+ * [method@UnlockOptionsWidget.get_choice].
  */
 
 /**
@@ -59,18 +58,6 @@
  * Option name for caching unlock for a certain amount of time.
  */
 
-/**
- * GcrUnlockOptionsWidget:
- *
- * An unlock options widget.
- */
-
-/**
- * GcrUnlockOptionsWidgetClass:
- *
- * Class for #GcrUnlockOptionsWidget.
- */
-
 enum {
        PROP_0,
        PROP_CHOICE,
diff --git a/ui/gcr-viewer-widget.c b/ui/gcr-viewer-widget.c
index 0c95fa2..4a03d5c 100644
--- a/ui/gcr-viewer-widget.c
+++ b/ui/gcr-viewer-widget.c
@@ -1,4 +1,3 @@
-/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
 /* gcr-viewer-widget: Widget for viewer
 
    Copyright (C) 2011 Collabora Ltd.
@@ -40,9 +39,7 @@
 #include <string.h>
 
 /**
- * SECTION:gcr-viewer-widget
- * @title: GcrViewerWidget
- * @short_description: A widget which shows certificates or keys
+ * GcrViewerWidget:
  *
  * A viewer widget which can display certificates and keys that are
  * located in files.
@@ -54,18 +51,6 @@ enum {
        PROP_DISPLAY_NAME
 };
 
-/**
- * GcrViewerWidget:
- *
- * A viewer widget object.
- */
-
-/**
- * GcrViewerWidgetClass:
- *
- * Class for #GcrViewerWidget
- */
-
 /*
  * Not yet figured out how to expose these without locking down our
  * implementation, the parent class we derive from.
@@ -557,7 +542,7 @@ gcr_viewer_widget_load_bytes (GcrViewerWidget *self,
  * may contain multiple parseable items if the format can contain multiple
  * items.
  *
- * This function will copy the data. Use gcr_viewer_widget_load_bytes() to avoid
+ * This function will copy the data. Use [method@ViewerWidget.load_bytes] to avoid
  * copying the data.
  */
 void
diff --git a/ui/gcr-viewer.c b/ui/gcr-viewer.c
index afd98aa..2ae3771 100644
--- a/ui/gcr-viewer.c
+++ b/ui/gcr-viewer.c
@@ -23,26 +23,19 @@
 #include "gcr-viewer.h"
 
 /**
- * SECTION:gcr-viewer
- * @title: GcrViewer
- * @short_description: A viewer which can hold renderers
+ * GcrViewer:
  *
- * A #GcrViewer is an abstract interface that represents a widget that can hold
+ * An abstract interface that represents a widget that can hold
  * various renderers and display their contents.
  *
- * The interaction between #GcrRenderer and #GcrViewer is not stable yet, and
- * so viewers cannot be implemented outside the Gcr library at this time.
+ * The interaction between [class@Renderer] and [class@Viewer] is not stable
+ * yet, and so viewers cannot be implemented outside the Gcr library at this
+ * time.
  *
- * Use the gcr_viewer_new() and gcr_viewer_new_scrolled() to get default
+ * Use the [func Viewer new] and [func@Viewer.new_scrolled] to get default
  * implementations of viewers.
  */
 
-/**
- * GcrViewer:
- *
- * An abstract viewer which displays renderers contents.
- */
-
 /**
  * GcrViewerIface:
  * @parent: The parent interface
@@ -99,7 +92,7 @@ gcr_viewer_new_scrolled (void)
 }
 
 /**
- * gcr_viewer_add_renderer:
+ * gcr_viewer_add_renderer: (virtual add_renderer)
  * @viewer: The viewer
  * @renderer: The renderer to add
  *
@@ -116,7 +109,7 @@ gcr_viewer_add_renderer (GcrViewer *viewer,
 }
 
 /**
- * gcr_viewer_insert_renderer:
+ * gcr_viewer_insert_renderer: (virtual insert_renderer)
  * @viewer: the viewer
  * @renderer: the renderer to insert
  * @before: (nullable): the renderer to insert before
@@ -136,7 +129,7 @@ gcr_viewer_insert_renderer (GcrViewer *viewer,
 }
 
 /**
- * gcr_viewer_remove_renderer:
+ * gcr_viewer_remove_renderer: (virtual remove_renderer)
  * @viewer: The viewer
  * @renderer: The renderer to remove
  *
@@ -153,7 +146,7 @@ gcr_viewer_remove_renderer (GcrViewer *viewer,
 }
 
 /**
- * gcr_viewer_count_renderers:
+ * gcr_viewer_count_renderers: (virtual count_renderers)
  * @viewer: The viewer
  *
  * Get the number of renderers present in the viewer.
@@ -169,7 +162,7 @@ gcr_viewer_count_renderers (GcrViewer *viewer)
 }
 
 /**
- * gcr_viewer_get_renderer:
+ * gcr_viewer_get_renderer: (virtual get_renderer)
  * @viewer: The viewer
  * @index_: The index of the renderer to get
  *


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