From 4bb63ced295ddd64a019ae49cfae191524a34f07 Mon Sep 17 00:00:00 2001
From: Stef Walter <stefw@collabora.co.uk>
Date: Thu, 9 Jun 2011 10:24:07 +0200
Subject: Complete documentation for message functionality.

---
 doc/p11-kit-docs.sgml    |  1 +
 doc/p11-kit-sections.txt |  6 ++++++
 p11-kit/modules.c        | 15 +++++++++++++++
 p11-kit/util.c           | 29 +++++++++++++++++++++++++++++
 4 files changed, 51 insertions(+)

diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml
index 2f7fdb2..f0b95bf 100644
--- a/doc/p11-kit-docs.sgml
+++ b/doc/p11-kit-docs.sgml
@@ -19,6 +19,7 @@
 		<xi:include href="xml/p11-kit.xml"/>
 		<xi:include href="xml/p11-kit-uri.xml"/>
 		<xi:include href="xml/p11-kit-util.xml"/>
+		<xi:include href="xml/p11-kit-future.xml"/>
 	</chapter>
 
 	<index id="api-index-full">
diff --git a/doc/p11-kit-sections.txt b/doc/p11-kit-sections.txt
index db1f4f7..36b9de2 100644
--- a/doc/p11-kit-sections.txt
+++ b/doc/p11-kit-sections.txt
@@ -56,3 +56,9 @@ CK_ULONG
 p11_kit_uri_result_t
 p11_kit_uri_type_t
 </SECTION>
+
+<SECTION>
+<FILE>p11-kit-future</FILE>
+p11_kit_be_quiet
+p11_kit_message
+</SECTION>
\ No newline at end of file
diff --git a/p11-kit/modules.c b/p11-kit/modules.c
index 757b4d2..eae7de3 100644
--- a/p11-kit/modules.c
+++ b/p11-kit/modules.c
@@ -649,6 +649,9 @@ _p11_kit_initialize_registered_unlocked_reentrant (void)
  * Use p11_kit_finalize_registered() to finalize these registered modules once
  * the caller is done with them.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the initialization succeeded, or an error code.
  */
 CK_RV
@@ -730,6 +733,9 @@ _p11_kit_finalize_registered_unlocked_reentrant (void)
  * process, then this function must be called the same number of times before
  * actual finalization will occur.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the finalization succeeded, or an error code.
  */
 
@@ -936,6 +942,9 @@ p11_kit_registered_option (CK_FUNCTION_LIST_PTR module, const char *field)
  * Custom initialization arguments cannot be supported when multiple consumers
  * load the same module.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the initialization was successful.
  */
 CK_RV
@@ -1001,6 +1010,9 @@ p11_kit_initialize_module (CK_FUNCTION_LIST_PTR module)
  * to use this function on registered modules if (and only if) they were
  * initialized using p11_kit_initialize_module() for some reason.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the finalization was successful.
  */
 CK_RV
@@ -1061,6 +1073,9 @@ p11_kit_finalize_module (CK_FUNCTION_LIST_PTR module)
  * Custom initialization arguments cannot be supported when multiple consumers
  * load the same module.
  *
+ * If this function fails, then an error message will be available via the
+ * p11_kit_message() function.
+ *
  * Returns: CKR_OK if the initialization was successful.
  */
 CK_RV
diff --git a/p11-kit/util.c b/p11-kit/util.c
index dda4703..fdf434b 100644
--- a/p11-kit/util.c
+++ b/p11-kit/util.c
@@ -46,6 +46,16 @@
 #include <stdio.h>
 #include <string.h>
 
+/**
+ * SECTION:p11-kit-future
+ * @title: Future
+ * @short_description: Future Unstable API
+ *
+ * API that is not yet stable enough to be enabled by default. In all likelyhood
+ * this will be included in the next release. To use this API you must define a
+ * MACRO. See the p11-kit.h header for more details.
+ */
+
 #define MAX_MESSAGE 512
 static pthread_once_t key_once = PTHREAD_ONCE_INIT;
 static pthread_key_t message_buffer_key = 0;
@@ -180,6 +190,12 @@ _p11_message (const char* msg, ...)
 	store_message_buffer (buffer, length);
 }
 
+/**
+ * p11_kit_be_quiet:
+ *
+ * Once this function is called, the p11-kit library will no longer print
+ * failure or warning messages to stderr.
+ */
 void
 p11_kit_be_quiet (void)
 {
@@ -188,6 +204,19 @@ p11_kit_be_quiet (void)
 	_p11_unlock ();
 }
 
+/**
+ * p11_kit_message:
+ *
+ * Gets the failure message for a recently called p11-kit function, which
+ * returned a failure code on this thread. Not all functions set this message.
+ * Each function that does so, will note it in its documentation.
+ *
+ * If the most recent p11-kit function did not fail, then this will return NULL.
+ * The string is owned by the p11-kit library and is only valid on the same
+ * thread that the failed function executed on.
+ *
+ * Returns: The last failure message, or %NULL.
+ */
 const char*
 p11_kit_message (void)
 {
-- 
cgit v1.1