Documentation enhancements

1 files changed, 29 insertions, 23 deletions

diff --git a/libcsoap/soap-xmlsec.h b/libcsoap/soap-xmlsec.h
index 31ee408..7026d9c 100644
--- a/libcsoap/soap-xmlsec.h
+++ b/libcsoap/soap-xmlsec.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-xmlsec.h,v 1.5 2006/12/06 11:27:21 m0gg Exp $
+ *  $Id: soap-xmlsec.h,v 1.6 2006/12/09 09:35:00 m0gg Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2006 Heiko Ronsdorf
@@ -26,12 +26,12 @@
 
 /** @file
  *
- * Web Services Security
+ * \section Web Services Security
  *
  * This module is implemented using the xmlsec1 library.
  *
  * @author	H. Ronsdorf
- * @version	$Revision: 1.5 $
+ * @version	$Revision: 1.6 $
  *
  * @see		http://www.w3.org/TR/SOAP-dsig/
  * @see		http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss
@@ -44,14 +44,14 @@
 
 /**
  *
- * Commandline argument to enabled WS-Security.
+ * Commandline argument to enable WS-Security.
  *
  */
 #define CSOAP_ENABLE_XMLSEC	"-CSOAPxmlsec"
 
 /**
  *
- * Commandline argument to set the keyfile. If this argument is not specified a
+ * Commandline argument to set the keyfile. If this argument is not specified, a
  * random key will be used.
  *
  */
@@ -71,6 +71,12 @@
  */
 #define CSOAP_XMLSEC_CERTFILE	"-CSOAPcertfile"
 
+/** @defgroup xmlsec_errors XML-security errors
+ *
+ * Various errors related to XML-security
+ *
+ */
+/*@{*/
 #define XMLSEC_ERROR			5100
 #define XMLSEC_ERROR_GENERIC		(XMLSEC_ERROR + 0)
 #define XMLSEC_ERROR_KEYSTORE		(XMLSEC_ERROR + 10)
@@ -84,6 +90,7 @@
 #define XMLSEC_ERROR_SIGN_INIT		(XMLSEC_ERROR + 90)
 #define XMLSEC_ERROR_ENCRYPT		(XMLSEC_ERROR + 100)
 #define XMLSEC_ERROR_ENCRYPT_INIT	(XMLSEC_ERROR + 110)
+/*@}*/
 
 #ifdef __cplusplus
 extern "C" {
@@ -119,17 +126,17 @@ extern herror_t soap_xmlsec_client_init_args(int argc, char **argv);
  * the commandline. Our way to create a <SOAP-SEC:Signature> header entry is as
  * follows:
  *
- * # Prepare the target SOAP Envelope with the body and necessary headers.
- * # Create a template of a <ds:Signature> element. The template is assumed to
+ * - Prepare the target SOAP Envelope with the body and necessary headers.
+ * - Create a template of a <ds:Signature> element. The template is assumed to
  *   contain empty contents for <ds:DigestValue> or <ds:SignatureValue> elements,
  *   but contains appropriate values for the elements such as
  *   <ds:SignatureMethod> and <ds:Reference> required to calculate them.
- * # Create a new header entry <SOAP-SEC:Signature> and add the template to this
+ * - Create a new header entry <SOAP-SEC:Signature> and add the template to this
  *   entry.
- * # Add the header entry <SOAP-SEC:Signature> to the SOAP Header.
- * # Add the SOAP "actor" and "mustUnderstand" attributes to the entry, if
+ * - Add the header entry <SOAP-SEC:Signature> to the SOAP Header.
+ * - Add the SOAP "actor" and "mustUnderstand" attributes to the entry, if
  *   necessary.
- * # Calculate the <ds:DigestValue> and <ds:SignatureValue> elements according
+ * - Calculate the <ds:DigestValue> and <ds:SignatureValue> elements according
  *   to the core generation of the XML-Signature specification.
  *
  * XPath filtering can be used to specify objects to be signed, as described in
@@ -144,12 +151,12 @@ extern herror_t soap_xmlsec_client_init_args(int argc, char **argv);
  * in the XML-Signature specification may be useful when signing the entire
  * Envelope including other header entries, if any.
  *
- * @param envelope The SOAP envelope to be signed.
+ * @param context The SOAP context to be signed.
  *
  * @return H_OK on success
  *
- * @see http://www.w3.org/TR/SOAP-dsig/,
- *      http://www.w3.org/TR/xmldsig-core/
+ * @see http://www.w3.org/TR/SOAP-dsig/
+ * @see http://www.w3.org/TR/xmldsig-core/
  *
  */
 extern herror_t soap_xmlsec_sign(struct SoapCtx *context);
@@ -159,23 +166,23 @@ extern herror_t soap_xmlsec_sign(struct SoapCtx *context);
  * Verify a XML documents signature contained in a SOAP Envelope. The validation
  * of a <SOAP-SEC:Signature> header entry fails if:
  *
- * # The syntax of the content of the header entry does not conform to SOAP
+ * - The syntax of the content of the header entry does not conform to SOAP
  *   Security Extensions: Digital Signature specification, or
- * # The validation of the signature contained in the header entry fails
+ * - The validation of the signature contained in the header entry fails
  *   according to the core validation of the XML-Signature specification, or
- * # The receiving application program rejects the signature for some reason
+ * - The receiving application program rejects the signature for some reason
  *   (e.g., the signature is created by an untrusted key).
  *
  * If the validation of the signature header entry fails, applications MAY report
  * the failure to the sender. It is out of the scope of this library how to deal
  * with it.
  *
- * @param envelope The SOAP envelope to be verified.
+ * @param context The SOAP context to be verified.
  *
  * @return H_OK on success
  *
- * @see http://www.w3.org/TR/SOAP-dsig/,
- *      http://www.w3.org/TR/xmldsig-core/
+ * @see http://www.w3.org/TR/SOAP-dsig/
+ * @see http://www.w3.org/TR/xmldsig-core/
  *
  */
 extern herror_t soap_xmlsec_verify(struct SoapCtx *context);
@@ -184,7 +191,7 @@ extern herror_t soap_xmlsec_verify(struct SoapCtx *context);
  *
  * Encrypt a XML document contained in a SOAP envelope.
  *
- * @param envelope The SOAP envelope to be encrypted.
+ * @param context The SOAP context to be encrypted.
  *
  * @return H_OK on success
  *
@@ -195,14 +202,13 @@ extern herror_t soap_xmlsec_encrypt(struct SoapCtx *context);
  *
  * Decrupt a XML document contained in a SOAP envelope.
  *
- * @param envelope The SOAP envelope to be decrypted.
+ * @param context The SOAP context to be decrypted.
  *
  * @return H_OK on success
  *
  */
 extern herror_t soap_xmlsec_decrypt(struct SoapCtx *context);
 
-
 /**
  *
  * Frees the resources needed by the XML security subsystem.