Complete documentation for message functionality.

2 files changed, 44 insertions, 0 deletions

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)
 {