Documentation enhancements

5 files changed, 187 insertions, 9 deletions

diff --git a/libcsoap/soap-env.h b/libcsoap/soap-env.h
index 95867d7..d1c0d3e 100644
--- a/libcsoap/soap-env.h
+++ b/libcsoap/soap-env.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-env.h,v 1.18 2006/11/25 15:06:57 m0gg Exp $
+ *  $Id: soap-env.h,v 1.19 2006/11/27 10:49:57 m0gg Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -24,6 +24,92 @@
 #ifndef __csoap_env_h
 #define __csoap_env_h
 
+/** @file
+ *
+ * SOAP Envelope
+ *
+ * A SOAP message is an XML document that consists of a mandatory SOAP envelope,
+ * an optional SOAP header, and a mandatory SOAP body. This XML document is
+ * referred to as a SOAP message. The namespace identifier for the elements and
+ * attributes defined in this section is
+ * "http://schemas.xmlsoap.org/soap/envelope/". A SOAP message contains the
+ * following:
+ * - The Envelope is the top element of the XML document representing the
+ *   message. 
+ * - The Header is a generic mechanism for adding features to a SOAP message in a
+ *   decentralized manner without prior agreement between the communicating
+ *   parties. SOAP defines a few attributes that can be used to indicate who
+ *   should deal with a feature and whether it is optional or mandatory.
+ * - The Body is a container for mandatory information intended for the ultimate
+ *   recipient of the message. SOAP defines one element for the body, which is
+ *   the Fault element used for reporting errors. 
+ *
+ * The grammar rules are as follows: 
+ * - Envelope 
+ * -# The element name is "Envelope". 
+ * -# The element MUST be present in a SOAP message 
+ * -# The element MAY contain namespace declarations as well as additional
+ *    attributes. If present, such additional attributes MUST be
+ *    namespace-qualified. Similarly, the element MAY contain additional sub
+ *    elements. If present these elements MUST be namespace-qualified and MUST
+ *    follow the SOAP Body element. 
+ * - Header
+ * -# The element name is "Header". 
+ * -# The element MAY be present in a SOAP message. If present, the element MUST
+ *    be the first immediate child element of a SOAP Envelope element. 
+ * -# The element MAY contain a set of header entries each being an immediate
+ *    child element of the SOAP Header element. All immediate child elements of
+ *    the SOAP Header element MUST be namespace-qualified. 
+ * - Body
+ * -# The element name is "Body". 
+ * -# The element MUST be present in a SOAP message and MUST be an immediate
+ *    child element of a SOAP Envelope element. It MUST directly follow the SOAP
+ *    Header element if present. Otherwise it MUST be the first immediate child
+ *    element of the SOAP Envelope element. 
+ * -# The element MAY contain a set of body entries each being an immediate child
+ *    element of the SOAP Body element. Immediate child elements of the SOAP Body
+ *    element MAY be namespace-qualified. SOAP defines the SOAP Fault element,
+ *    which is used to indicate error messages (see section 4.4).
+ *
+ * SOAP encodingStyle Attribute
+ *
+ * The SOAP encodingStyle global attribute can be used to indicate the
+ * serialization rules used in a SOAP message. This attribute MAY appear on any
+ * element, and is scoped to that element's contents and all child elements not
+ * themselves containing such an attribute, much as an XML namespace declaration
+ * is scoped. There is no default encoding defined for a SOAP message.
+ *
+ * The attribute value is an ordered list of one or more URIs identifying the
+ * serialization rule or rules that can be used to deserialize the SOAP message
+ * indicated in the order of most specific to least specific. Examples of values
+ * are:
+ * - "http://schemas.xmlsoap.org/soap/encoding/"
+ * - "http://my.host/encoding/restricted http://my.host/encoding/"
+ * - ""
+ * The serialization rules defined by SOAP are identified by the URI
+ * "http://schemas.xmlsoap.org/soap/encoding/". Messages using this particular
+ * serialization SHOULD indicate this using the SOAP encodingStyle attribute. In
+ * addition, all URIs syntactically beginning with
+ * "http://schemas.xmlsoap.org/soap/encoding/" indicate conformance with the SOAP
+ * encoding rules (though with potentially tighter rules added). A value of the
+ * zero-length URI ("") explicitly indicates that no claims are made for the
+ * encoding style of contained elements. This can be used to turn off any claims
+ * from containing elements.
+ *
+ * Envelope Versioning Model
+ *
+ * SOAP does not define a traditional versioning model based on major and minor
+ * version numbers. A SOAP message MUST have an Envelope element associated with
+ * the "http://schemas.xmlsoap.org/soap/envelope/" namespace. If a message is
+ * received by a SOAP application in which the SOAP Envelope element is
+ * associated with a different namespace, the application MUST treat this as a
+ * version error and discard the message. If the message is received through a
+ * request/response protocol such as HTTP, the application MUST respond with a
+ * SOAP VersionMismatch faultcode message using the SOAP
+ * "http://schemas.xmlsoap.org/soap/envelope/" namespace.
+ *
+ */
+
 /**
  *
  * The SOAP envelope namespace
diff --git a/libcsoap/soap-fault.h b/libcsoap/soap-fault.h
index 1a11365..8ced1c4 100644
--- a/libcsoap/soap-fault.h
+++ b/libcsoap/soap-fault.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-fault.h,v 1.6 2006/11/21 20:59:02 m0gg Exp $
+ *  $Id: soap-fault.h,v 1.7 2006/11/27 10:49:57 m0gg Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -24,7 +24,7 @@
 #ifndef __csoap_fault_h
 #define __csoap_fault_h
 
-/**
+/** @file
  *
  * The SOAP Fault element is used to carry error and/or status information within
  * a SOAP message. If present, the SOAP Fault element MUST appear as a body entry
@@ -59,6 +59,9 @@
  *   entries. Detailed error information belonging to header entries MUST be
  *   carried within header entries.
  *
+ *   @author	F. Ayaz
+ *   @version	$Revision: 1.7 $
+ *
  */
  
 /**
diff --git a/libcsoap/soap-nhttp.h b/libcsoap/soap-nhttp.h
index ebf107d..2ce59e4 100644
--- a/libcsoap/soap-nhttp.h
+++ b/libcsoap/soap-nhttp.h
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: soap-nhttp.h,v 1.3 2006/11/26 20:13:05 m0gg Exp $
+*  $Id: soap-nhttp.h,v 1.4 2006/11/27 10:49:57 m0gg Exp $
 *
 * CSOAP Project:  A SOAP client/server library in C
 * Copyright (C) 2007 Heiko Ronsdorf
@@ -24,6 +24,31 @@
 #ifndef __soap_nhttp_h
 #define __soap_nhttp_h
 
+/** @file
+ *
+ * Using SOAP in HTTP
+ *
+ * This section describes how to use SOAP within HTTP with or without using the
+ * HTTP Extension Framework. Binding SOAP to HTTP provides the advantage of being
+ * able to use the formalism and decentralized flexibility of SOAP with the rich
+ * feature set of HTTP. Carrying SOAP in HTTP does not mean that SOAP overrides
+ * existing semantics of HTTP but rather that the semantics of SOAP over HTTP
+ * maps naturally to HTTP semantics.
+ *
+ * SOAP naturally follows the HTTP request/response message model providing SOAP
+ * request parameters in a HTTP request and SOAP response parameters in a HTTP
+ * response. Note, however, that SOAP intermediaries are NOT the same as HTTP
+ * intermediaries. That is, an HTTP intermediary addressed with the HTTP
+ * Connection header field cannot be expected to inspect or process the SOAP
+ * entity body carried in the HTTP request.
+ *
+ * HTTP applications MUST use the media type "text/xml" according to RFC 2376
+ * when including SOAP entity bodies in HTTP messages.
+ *
+ * @see http://www.ietf.org/rfc/rfc2376.txt
+ *
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
diff --git a/libcsoap/soap-service.h b/libcsoap/soap-service.h
index e999e2e..33d69f6 100644
--- a/libcsoap/soap-service.h
+++ b/libcsoap/soap-service.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-service.h,v 1.8 2006/11/23 15:27:33 m0gg Exp $
+ *  $Id: soap-service.h,v 1.9 2006/11/27 10:49:57 m0gg Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -24,6 +24,22 @@
 #ifndef __csoap_service_h
 #define __csoap_service_h
 
+/** @file
+ *
+ * A Web service is a software system designed to support interoperable
+ * machine-to-machine interaction over a network. It has an interface described
+ * in a machine-processable format (specifically WSDL). Other systems interact
+ * with the Web service in a manner prescribed by its description using SOAP
+ * messages, typically conveyed using HTTP with an XML serialization in
+ * conjunction with other Web-related standards.
+ *
+ * @see http://www.w3.org/TR/wslc/,
+ *      http://www.w3.org/TR/wsdl,
+ *      http://www.w3.org/TR/owl-ref/
+ *
+ */
+
+
 typedef herror_t (*SoapServiceFunc)(struct SoapCtx *request, struct SoapCtx *response);
 
 typedef struct _SoapService
diff --git a/libcsoap/soap-wsil.h b/libcsoap/soap-wsil.h
index 3acaf42..0eedf67 100644
--- a/libcsoap/soap-wsil.h
+++ b/libcsoap/soap-wsil.h
@@ -1,8 +1,8 @@
 /******************************************************************
- *  $Id: soap-wsil.h,v 1.1 2006/11/23 13:20:46 m0gg Exp $
+ *  $Id: soap-wsil.h,v 1.2 2006/11/27 10:49:57 m0gg Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
- * Copyright (C) 2003  Ferhat Ayaz
+ * Copyright (C) 2006 H. Ronsdorf
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -19,11 +19,56 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA  02111-1307, USA.
  * 
- * Email: ferhatayaz@yahoo.com
+ * Email: hero@persua.de
  ******************************************************************/
 #ifndef __csoap_wsil_h
 #define __csoap_wsil_h
 
+/** @file
+ *
+ * WS-Inspection
+ *
+ * The WS-Inspection specification provides an XML format for assisting in the
+ * inspection of a site for available services and a set of rules for how
+ * inspection related information should be made available for consumption. A
+ * WS-Inspection document provides a means for aggregating references to
+ * pre-existing service description documents which have been authored in any
+ * number of formats. These inspection documents are then made available at the
+ * point-of-offering for the service as well as through references which may be
+ * placed within a content medium such as HTML.
+ *
+ * Specifications have been proposed to describe Web Services at different levels
+ * and from various perspectives. It is the goal of the proposed Web Services
+ * Description Language (WSDL) to describe services at a functional level. The
+ * Universal Description, Discovery, and Integration (UDDI) schema aims at
+ * providing a more business-centric perspective. What has not yet been provided
+ * by these proposed standards is the ability to tie together, at the point of
+ * offering for a service, these various sources of information in a manner which
+ * is both simple to create and use. the WS-Inspection specification addresses
+ * this need by defining an XML grammar which facilitates the aggregation of
+ * references to different types of service description documents, and then
+ * provides a well defined pattern of usage for instances of this grammar. By
+ * doing this, the WS-Inspection specification provides a means by which to
+ * inspect sites for service offerings.
+ *
+ * Repositories already exist where descriptive information about Web services
+ * has been gathered together. The WS-Inspection specification provides
+ * mechanisms with which these existing repositories can be referenced and
+ * utilized, so that the information contained in them need not be duplicated if
+ * such a duplication is not desired.
+ *
+ * @author	H. Ronsorf
+ * @version	$Revision: 1.2 $
+ *
+ * @see http://www-128.ibm.com/developerworks/library/specification/ws-wsilspec/
+ *
+ */
+
+/**
+ *
+ * Commandline argument to enabled automatic WSIL generation.
+ *
+ */
 #define CSOAP_ENABLE_WSIL	"-CSOAPwsil"
 
 #ifdef __cplusplus
@@ -32,13 +77,16 @@ extern "C" {
 
 /**
  *
- * Initializes the WSIL HTTP interface with commandline arguments.
+ * Initializes the WSIL HTTP interface with commandline arguments. The generated
+ * WSIL document can be seen at http://servername/inspection.wsil.
  *
  * @param argc commandline arg count
  * @param argv commandline arg vector
  *
  * @returns H_OK on success
  *
+ * @see CSOAP_ENABLE_WSIL
+ *
  */
 extern herror_t soap_wsil_init_args(int argc, char *argv[]);