[gcr/gi-docsgen: 2/2] WIP
- From: Niels De Graef <nielsdg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gcr/gi-docsgen: 2/2] WIP
- Date: Thu, 30 Sep 2021 15:58:16 +0000 (UTC)
commit 3106836989e85048e91ab647c3ca8e60489a4589
Author: Niels De Graef <nielsdegraef gmail com>
Date: Thu Sep 30 17:58:09 2021 +0200
WIP
gck/gck-attributes.c | 202 ++++++++++++++++++++++++---------------------------
gck/gck-module.c | 53 ++++++--------
gck/gck-modules.c | 16 ++--
gck/gck-object.c | 29 +++-----
gck/gck-session.c | 53 +++++++-------
5 files changed, 162 insertions(+), 191 deletions(-)
---
diff --git a/gck/gck-attributes.c b/gck/gck-attributes.c
index 8612a28..f681a9c 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,7 +430,7 @@ 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
+ * 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
@@ -474,7 +476,7 @@ 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
+ * 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
@@ -516,7 +518,7 @@ 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
+ * 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
@@ -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
@@ -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,15 +1368,6 @@ 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.
@@ -1553,7 +1546,7 @@ gck_attribute_get_data (const GckAttribute *attr,
* 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
@@ -1586,7 +1579,7 @@ gck_attribute_init (GckAttribute *attr,
* state. Specifically this sets the value length to (CK_ULONG)-1
* 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
@@ -1607,7 +1600,7 @@ gck_attribute_init_invalid (GckAttribute *attr,
* 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
@@ -1629,7 +1622,7 @@ gck_attribute_init_empty (GckAttribute *attr, gulong attr_type)
* 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
@@ -1651,7 +1644,7 @@ gck_attribute_init_boolean (GckAttribute *attr,
* 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
@@ -1677,7 +1670,7 @@ gck_attribute_init_date (GckAttribute *attr,
* 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
@@ -1701,7 +1694,7 @@ gck_attribute_init_ulong (GckAttribute *attr,
* 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
@@ -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.
@@ -1892,8 +1885,8 @@ gck_attribute_dup (const GckAttribute *attr)
* 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-module.c b/gck/gck-module.c
index 1fa7584..e85050e 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,
@@ -466,11 +459,11 @@ gck_module_initialize_finish (GAsyncResult *result,
* gck_module_new: (skip)
* @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.c b/gck/gck-object.c
index 1521626..177f376 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.
+ * [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,
diff --git a/gck/gck-session.c b/gck/gck-session.c
index 99f7cdd..550a4b4 100644
--- a/gck/gck-session.c
+++ b/gck/gck-session.c
@@ -1451,10 +1451,10 @@ gck_session_create_object (GckSession *self, GckAttributes *attrs,
* @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 +1481,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 +1498,6 @@ gck_session_create_object_finish (GckSession *self, GAsyncResult *result, GError
}
-
/* FIND OBJECTS */
typedef struct _FindObjects {
@@ -1588,7 +1587,7 @@ perform_find_objects (FindObjects *args)
* 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
@@ -1632,7 +1631,7 @@ gck_session_find_handles (GckSession *self,
* 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 +1693,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 +1732,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 +1795,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 +1863,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 +1892,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 +1948,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 +2072,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 +2096,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 +2142,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 +2258,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 +2291,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 +2346,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,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
