[gcr/gi-docsgen] docs: Port from gtk-doc to gi-docgen
- From: Niels De Graef <nielsdg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gcr/gi-docsgen] docs: Port from gtk-doc to gi-docgen
- Date: Tue, 9 Nov 2021 22:57:45 +0000 (UTC)
commit 3f659531d5a18a415e0ee6e253af747568f469ab
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
.gitlab-ci.yml | 2 +-
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 +-
91 files changed, 1033 insertions(+), 3667 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 1049863..a7da4f9 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -3,7 +3,7 @@ stages:
- deploy
variables:
- DEPENDENCIES: dbus-daemon diffutils gcc gtk-doc libsecret-devel meson ninja-build openssh openssh-clients
python redhat-rpm-config systemd-devel
+ DEPENDENCIES: dbus-daemon diffutils gcc gi-docgen libsecret-devel meson ninja-build openssh
openssh-clients python redhat-rpm-config systemd-devel
fedora:Werror:
image: fedora:latest
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..f260dc6
--- /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 / 'gck'),
+ '--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
+----------------
+[](class.ComboSelector.html)
+[](class.ListSelector.html)
+[](class.TreeSelector.html)
+
+Display widgets
+---------------
+[](class.CertificateWidget.html)
+[](class.KeyWidget.html)
+[](class.ViewerWidget.html)
+
+Import widgets
+--------------
+[](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#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]
