GNOME.org
 

[gcr] Documentation fixes

commit 1295eca404dd02396abfcab35e3b5dda000c1712
Author: Stef Walter <stefw gnome org>
Date:   Tue Jun 26 08:47:08 2012 +0200

    Documentation fixes
    
     * Clean up documentation and introspection warnings
     * Separate GcrImportInteraction docs into own page

 docs/reference/gcr/gcr-docs.sgml    |    1 +
 docs/reference/gcr/gcr-sections.txt |   14 +++++++++---
 gck/gck-attributes.c                |   23 +------------------
 gck/gck-enumerator.c                |    2 +-
 gcr/gcr-certificate-chain.c         |    6 -----
 gcr/gcr-import-interaction.c        |   39 ++++++++++++----------------------
 gcr/gcr-library.c                   |    6 -----
 gcr/gcr-parser.c                    |    2 +-
 gcr/gcr-prompt-dialog.c             |    8 +++---
 gcr/gcr-system-prompt.c             |    6 ++--
 10 files changed, 36 insertions(+), 71 deletions(-)
---
diff --git a/docs/reference/gcr/gcr-docs.sgml b/docs/reference/gcr/gcr-docs.sgml
index 8756344..d9c4c86 100644
--- a/docs/reference/gcr/gcr-docs.sgml
+++ b/docs/reference/gcr/gcr-docs.sgml
@@ -60,6 +60,7 @@
 		<title>Storage</title>
 		<xi:include href="xml/gcr-trust.xml"/>
 		<xi:include href="xml/gcr-importer.xml"/>
+		<xi:include href="xml/gcr-import-interaction.xml"/>
 		<xi:include href="xml/gcr-parser.xml"/>
 	</part>
 
diff --git a/docs/reference/gcr/gcr-sections.txt b/docs/reference/gcr/gcr-sections.txt
index de8b840..be85461 100644
--- a/docs/reference/gcr/gcr-sections.txt
+++ b/docs/reference/gcr/gcr-sections.txt
@@ -130,10 +130,6 @@ gcr_importer_register_well_known
 gcr_importer_create_for_parsed
 gcr_importer_queue_for_parsed
 gcr_importer_queue_and_filter_for_parsed
-gcr_import_interaction_supplement_prep
-gcr_import_interaction_supplement
-gcr_import_interaction_supplement_async
-gcr_import_interaction_supplement_finish
 <SUBSECTION Standard>
 GCR_IMPORTER
 GCR_IS_IMPORTER
@@ -150,6 +146,16 @@ gcr_import_interaction_get_type
 </SECTION>
 
 <SECTION>
+<FILE>gcr-import-interaction</FILE>
+GcrImportInteraction
+GcrImportInteractionIface
+gcr_import_interaction_supplement_prep
+gcr_import_interaction_supplement
+gcr_import_interaction_supplement_async
+gcr_import_interaction_supplement_finish
+</SECTION>
+
+<SECTION>
 <FILE>gcr-import-button</FILE>
 GcrImportButton
 GcrImportButtonClass
diff --git a/gck/gck-attributes.c b/gck/gck-attributes.c
index 5c86f31..d05287a 100644
--- a/gck/gck-attributes.c
+++ b/gck/gck-attributes.c
@@ -40,15 +40,9 @@
  * 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.
- */
-
-/**
- * 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 G_MAXULONG if the attribute is
  *
- * This structure represents a PKCS11 CK_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));
@@ -1395,19 +1389,6 @@ gck_builder_clear (GckBuilder *builder)
 }
 
 /**
- * SECTION:gck-attribute
- * @title: GckAttribute
- * @short_description: A PKCS11 attribute.
- *
- * This structure represents a PKCS11 CK_ATTRIBUTE. These attributes contain information
- * about a PKCS11 object. Use gck_object_get() or gck_object_set() to set and retrieve
- * 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.
- */
-
-/**
  * GckAttribute:
  * @type: The attribute type, such as CKA_LABEL.
  * @value: (array length=length): The value of the attribute. May be NULL.
diff --git a/gck/gck-enumerator.c b/gck/gck-enumerator.c
index 1945797..0c6cc02 100644
--- a/gck/gck-enumerator.c
+++ b/gck/gck-enumerator.c
@@ -921,7 +921,7 @@ gck_enumerator_get_chained (GckEnumerator *self)
 }
 
 /**
- * gck_enumerator_set_interaction:
+ * gck_enumerator_set_chained:
  * @self: the enumerator
  * @chained: (allow-none): the chained enumerator or %NULL
  *
diff --git a/gcr/gcr-certificate-chain.c b/gcr/gcr-certificate-chain.c
index 9d8258a..5637634 100644
--- a/gcr/gcr-certificate-chain.c
+++ b/gcr/gcr-certificate-chain.c
@@ -73,12 +73,6 @@
 
 
 /**
- * GCR_TYPE_CERTIFICATE_CHAIN_STATUS:
- *
- * The flags #GType for #GcrCertificateChainFlags.
- */
-
-/**
  * GcrCertificateChain:
  *
  * A chain of certificates.
diff --git a/gcr/gcr-import-interaction.c b/gcr/gcr-import-interaction.c
index 0c5a293..50060f3 100644
--- a/gcr/gcr-import-interaction.c
+++ b/gcr/gcr-import-interaction.c
@@ -26,42 +26,31 @@
 #include "gcr-import-interaction.h"
 
 /**
- * SECTION:gcr-importer
- * @title: GcrImporter
- * @short_description: Import certificates and keys
+ * SECTION:gcr-import-interaction
+ * @title: GcrImportInteraction
+ * @short_description: User interaction during importing
  *
- * 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.
+ * 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.
  *
- * An importer gets passed a #GcrParser 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
- * 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.
+ * It must be implemented on a derived class of #GTlsInteraction
  */
 
 /**
- * GcrImporter:
+ * GcrImportInteraction:
  *
- * Imports certificates and keys
+ * Interface implemented by the caller performing an import.
  */
 
 /**
- * GcrImporterIface:
+ * GcrImportInteractionIface:
  * @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()
+ * @supplement_prep: method which prepares for supplementing the given attributes before import
+ * @supplement: method which synchronously supplements attributes before import
+ * @supplement_async: method which asynchronously supplements attributes before import
+ * @supplement_finish: method which completes @supplement_async
  *
- * Interface implemented for a #GcrImporter.
+ * Interface implemented by implementations of #GcrImportInteraction.
  */
 
 typedef GcrImportInteractionIface GcrImportInteractionInterface;
diff --git a/gcr/gcr-library.c b/gcr/gcr-library.c
index f0e8461..43d2ee6 100644
--- a/gcr/gcr-library.c
+++ b/gcr/gcr-library.c
@@ -69,12 +69,6 @@
  * This section is only here to supress warnings, and should not be displayed.
  */
 
-/**
- * GCR_DATA_ERROR:
- *
- * The #GError domain for data parsing errors.
- */
-
 G_LOCK_DEFINE_STATIC (modules);
 static GList *all_modules = NULL;
 static gboolean initialized_modules = FALSE;
diff --git a/gcr/gcr-parser.c b/gcr/gcr-parser.c
index b617a24..430288a 100644
--- a/gcr/gcr-parser.c
+++ b/gcr/gcr-parser.c
@@ -92,7 +92,7 @@
  */
 
 /**
- * GcrDataError
+ * GcrDataError:
  * @GCR_ERROR_FAILURE: Failed to parse or serialize the data
  * @GCR_ERROR_UNRECOGNIZED: The data was unrecognized or unsupported
  * @GCR_ERROR_CANCELLED: The operation was cancelled
diff --git a/gcr/gcr-prompt-dialog.c b/gcr/gcr-prompt-dialog.c
index 928ef84..48d324e 100644
--- a/gcr/gcr-prompt-dialog.c
+++ b/gcr/gcr-prompt-dialog.c
@@ -773,7 +773,7 @@ gcr_prompt_dialog_class_init (GcrPromptDialogClass *klass)
 	g_object_class_override_property (gobject_class, PROP_CANCEL_LABEL, "cancel-label");
 
 	/**
-	 * GcrPromptDialog:password-visible
+	 * GcrPromptDialog:password-visible:
 	 *
 	 * Whether the password entry is visible or not.
 	 */
@@ -782,7 +782,7 @@ gcr_prompt_dialog_class_init (GcrPromptDialogClass *klass)
 	                                 FALSE, G_PARAM_READABLE));
 
 	/**
-	 * GcrPromptDialog:confirm-visible
+	 * GcrPromptDialog:confirm-visible:
 	 *
 	 * Whether the password confirm entry is visible or not.
 	 */
@@ -791,7 +791,7 @@ gcr_prompt_dialog_class_init (GcrPromptDialogClass *klass)
 	                                 FALSE, G_PARAM_READABLE));
 
 	/**
-	 * GcrPromptDialog:warning-visible
+	 * GcrPromptDialog:warning-visible:
 	 *
 	 * Whether the warning label is visible or not.
 	 */
@@ -800,7 +800,7 @@ gcr_prompt_dialog_class_init (GcrPromptDialogClass *klass)
 	                                 FALSE, G_PARAM_READABLE));
 
 	/**
-	 * GcrPromptDialog:choice-visible
+	 * GcrPromptDialog:choice-visible:
 	 *
 	 * Whether the choice check box is visible or not.
 	 */
diff --git a/gcr/gcr-system-prompt.c b/gcr/gcr-system-prompt.c
index 08b2db5..b06358b 100644
--- a/gcr/gcr-system-prompt.c
+++ b/gcr/gcr-system-prompt.c
@@ -437,7 +437,7 @@ gcr_system_prompt_class_init (GcrSystemPromptClass *klass)
 	g_type_class_add_private (gobject_class, sizeof (GcrSystemPromptPrivate));
 
 	/**
-	 * GcrSystemPrompt:bus-name
+	 * GcrSystemPrompt:bus-name:
 	 *
 	 * The DBus bus name of the prompter to use for prompting, or %NULL
 	 * for the default prompter.
@@ -447,7 +447,7 @@ gcr_system_prompt_class_init (GcrSystemPromptClass *klass)
 	                                 NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
 	/**
-	 * GcrSystemPrompt:timeout-seconds
+	 * GcrSystemPrompt:timeout-seconds:
 	 *
 	 * The timeout in seconds to wait when opening the prompt.
 	 */
@@ -456,7 +456,7 @@ gcr_system_prompt_class_init (GcrSystemPromptClass *klass)
 	                                 -1, G_MAXINT, -1, G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
 
 	/**
-	 * GcrSystemPrompt:secret-exchange
+	 * GcrSystemPrompt:secret-exchange:
 	 *
 	 * The #GcrSecretExchange to use when transferring passwords. A default
 	 * secret exchange will be used if this is not set.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]