Documentation fixup

11 files changed, 172 insertions, 85 deletions

diff --git a/libcsoap/soap-server.h b/libcsoap/soap-server.h
index 8cad6ff..4a850a8 100644
--- a/libcsoap/soap-server.h
+++ b/libcsoap/soap-server.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-server.h,v 1.20 2006/12/10 19:21:06 m0gg Exp $
+ *  $Id: soap-server.h,v 1.21 2006/12/11 08:13:19 m0gg Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -28,21 +28,72 @@
  *
  * @mainpage Project overview
  *
- * @section seq_intro Introduction
+ * @section project_intro_sec Introduction
  *
  * cSOAP is a client/server SOAP library implemented in pure C. It comes with
- * embedded transport servers for UDP and HTTP (nanohttp). The transferred XML
+ * embedded transport servers for UDP and HTTP (nanoHTTP). The transferred XML
  * structures are handled by libxml2.
  *
- * @section seq_features Features
+ * @section project_features_sec Features
  *
+ * - @subpage soap_page
  * - different transport services
- *   - @ref nanohttp_page (HTTP including SSL)
+ *   - @subpage nanohttp_page (HTTP including SSL)
  *   - client/server UDP transport service (multicast)
  * - attachments via MIME
  * - message based security (XML encryption/signation)
  * - automatic generation of WS-Inspection
  *
+ * @section howto_sec HOWTOs and coding examples
+ *
+ * - @ref nanohttp_client_page
+ * - @ref nanohttp_server_page
+ * - @ref nanohttp_mime_page
+ * - @ref csoap_client_page
+ * - @ref csoap_server_page
+ * - @ref csoap_mime_page
+ *
+ * @section help_sec How to help
+ *
+ * The development of cSOAP highly depends on your input! If you are trying
+ * cSOAP let us know what you think of it (do you miss certain features?). Even
+ * if you decide not to use it, please let us know why.
+ *
+ * @section projects_sec Projects that use cSOAP
+ *
+ * @subsection CompLearn (http://complearn.org/)
+ *
+ * CompLear is a suite of simple-to-use utilities that you can use to apply
+ * compression techniques to the process of discovering and learning patterns.
+ *
+ * @section downloads_sec Downloads
+ *
+ * @subsection Download stable release
+ *
+ * A stable release is a tested version of cSOAP. Download this package if you
+ * want to use it in your productive projects. 
+ *
+ * Download source code of libsoap-1.1.0.tar.gz:
+ * http://prdownloads.sourceforge.net/csoap/libsoap-1.1.0.tar.gz?download
+ *
+ * @subsection Download latest snapshot (nightly build)
+ *
+ * Latest snapshots are build nightly on a detected CVS commit. This is sometimes
+ * not very stable but in some case are snapshots the better choice then the
+ * stable version. This can happen if a very important bug was fixed or a new
+ * feature was introduced. It is recommend to join the mailinglist.
+ *
+ * Download latest snapshot (nightly build):
+ * http://csoap.sourceforge.net/downloads/libsoap-snapshot.tar.gz
+ *
+ * @subsection Checkout from CVS
+ *
+ * Do you want the latest source codes? You want to contribute a patch? Have you
+ * found a bug? Or whatever. You should check out csoap from CVS to play the game
+ * with us csoap developers.
+ *
+ * Web CVS access: http://csoap.cvs.sourceforge.net/csoap/libsoap/
+ *
  * @author	Ferhat Ayaz
  * @author	Michael Rans
  * @author	Matt Campbell
@@ -54,6 +105,19 @@
  * @see		http://www.libxml.org/
  * @see		http://www.openssl.org/
  * @see		http://www.aleksey.com/xmlsec/
+ *
+ */
+
+/** @page soap_page
+ *
+ * T.B.D.
+ *
+ * @section soap_howto_sec HOWTOs and coding examples
+ *
+ * - @ref csoap_client_page
+ * - @ref csoap_server_page
+ * - @ref csoap_mime_page
+ *
  */
 
 /** @page soap_server_page Howto write an SOAP server
@@ -149,8 +213,7 @@
  *
  *   xmlDocFormatDump(stdout, req->env->root->doc, 1);
  *
- *   err = soap_env_new_with_response(req->env, &res->env);
- *   if (err != H_OK)
+ *   if ((err = soap_env_new_with_response(req->env, &res->env)) != H_OK)
  *   {
  *     printf("soap_env_new_with_response failed (%s)\n", herror_message(err));
  *     return err;
diff --git a/nanohttp/nanohttp-base64.c b/nanohttp/nanohttp-base64.c
index 0e887d6..a0f4bec 100644
--- a/nanohttp/nanohttp-base64.c
+++ b/nanohttp/nanohttp-base64.c
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: nanohttp-base64.c,v 1.3 2006/11/28 23:45:57 m0gg Exp $
+*  $Id: nanohttp-base64.c,v 1.4 2006/12/11 08:13:19 m0gg Exp $
 *
 * CSOAP Project:  A http client/server library in C
 * Copyright (C) 2003  Ferhat Ayaz
@@ -128,6 +128,7 @@ void base64_decode_string(const unsigned char *instr, unsigned char *outstr)
 
 #ifdef BASE64_TEST_CASE_FROM_RFC2617
 #include <stdio.h>
+#include <strings.h>
 int main(int argc, char **argv) {
 
   unsigned char *instr = "QWxhZGRpbjpvcGVuIHNlc2FtZQ==";
diff --git a/nanohttp/nanohttp-client.h b/nanohttp/nanohttp-client.h
index b845ac3..9422997 100644
--- a/nanohttp/nanohttp-client.h
+++ b/nanohttp/nanohttp-client.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-client.h,v 1.34 2006/12/10 19:21:06 m0gg Exp $
+ *  $Id: nanohttp-client.h,v 1.35 2006/12/11 08:13:19 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -38,21 +38,22 @@
  *
  * @section client_sec Table of contents
  *
- * - Client initialization
- * - Connection initialization
- *   - SSL related functions
- * - Setting HTTP headers (optional)
- *   - Setting an HTTP header with uniq key
- *   - Setting multiple headers
- * - Fetch the network resource
- *   - @ref get_sec
- *   - @ref post_sec
- *   - MIME attachments
- * - Print out the result
- * - Connection cleanup
- * - Client cleanup
- *
- * @section init_sec Client initialization
+ * - @ref nanohttp_client_init_sec
+ * - @ref nanohttp_client_conn_init_sec
+ *   - @ref nanohttp_client_ssl_sec
+ * - @ref nanohttp_client_header_sec
+ *   - @ref nanohttp_client_header_uniq_sec
+ *   - @ref nanohttp_client_header_mult_sec
+ *   - @ref nanohttp_client_authorization_sec
+ * - @ref nanohttp_client_invoke_sec
+ *   - @ref nanohttp_client_get_sec
+ *   - @ref nanohttp_client_post_sec
+ *   - @ref nanohttp_client_mime_sec
+ * - @ref nanohttp_client_result_sec
+ * - @ref nanohttp_client_conn_cleanup_sec
+ * - @ref nanohttp_client_cleanup_sec
+ *
+ * @section nanohttp_client_init_sec Client initialization
  *
  * @code
  * int main(int argc, char **argv)
@@ -75,7 +76,7 @@
  *   }
  * @endcode
  *
- * @section conn_sec Connection initialization
+ * @section nanohttp_client_conn_init_sec Connection initialization
  *
  * @code
  *   if (!(conn = httpc_new()))
@@ -86,16 +87,22 @@
  *   }
  * @endcode
  *
- * @section ssl_sec SSL related functions
+ * @section nanohttp_client_ssl_sec SSL related functions
  *
  * T.B.D.
  *
- * @section header_sec Setting HTTP headers (optional)
+ * @ref nanohttp_ssl_page
+ *
+ * @section nanohttp_client_header_sec Setting HTTP headers (optional)
+ *
+ * @subsection nanohttp_client_header_uniq_sec Setting an header with uniq key
  *
  * @code
  *   httpc_set_header(conn, "my-key", "my-value");
  * @endcode
  *
+ * @subsection nanohttp_client_header_mult_sec Setting headers with the same key
+ *
  * @code
  *   httpc_add_header(conn, "Cookie", "name1:value1");
  *   httpc_add_header(conn, "Cookie", "name2:value2");
@@ -104,9 +111,19 @@
  * Please see @ref general_header_fields and @ref request_header_fields for more
  * information.
  *
- * @section fetch_sec Fetch the network resource
+ * @subsection nanohttp_client_authorization_sec HTTP autorization
  *
- * @subsection get_sec HTTP GET method
+ * @code
+ *   httpc_set_basic_authorization(conn, "username", "password");
+ * @endcode
+ *
+ * @code
+ *   httpc_set_basic_proxy_authorization(conn, "username", "password");
+ * @endcode
+ *
+ * @section nanohttp_client_invoke_sec Fetch the network resource
+ *
+ * @subsection nanohttp_client_get_sec HTTP GET method
  *
  * @code
  *   if ((status = httpc_get(conn, &result, argv[1])) != H_OK)
@@ -118,7 +135,7 @@
  *   }
  * @endcode
  *
- * @subsection post_sec HTTP POST method
+ * @subsection nanohttp_client_post_sec HTTP POST method
  *
  * @code
  *   if ((status = httpc_post_begin(conn, argv[1])) != H_OK)
@@ -146,11 +163,13 @@
  *   }
  * @endcode
  *
- * @section mime_sec MIME attachments
+ * @section nanohttp_client_mime_sec MIME attachments
  *
  * T.B.D.
  *
- * @section output_sec Print out the result
+ * @ref nanohttp_mime_page
+ *
+ * @section nanohttp_client_result_sec Print out the result
  *
  * @code
  *   while (http_input_stream_is_read(res->in))
@@ -160,13 +179,13 @@
  *   }
  * @endcode
  *
- * @section conn_clean_sec Connection cleanup
+ * @section nanohttp_client_conn_cleanup_sec Connection cleanup
  *
  * @code
  *   hresponse_free(res);
  * @endcode
  *
- * @section client_clean Client cleanup
+ * @section nanohttp_client_cleanup_sec Client cleanup
  *
  * @code
  *   httpc_free(conn);
diff --git a/nanohttp/nanohttp-common.h b/nanohttp/nanohttp-common.h
index 052f814..03fe18d 100644
--- a/nanohttp/nanohttp-common.h
+++ b/nanohttp/nanohttp-common.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-common.h,v 1.43 2006/12/10 19:21:06 m0gg Exp $
+ *  $Id: nanohttp-common.h,v 1.44 2006/12/11 08:13:19 m0gg Exp $
  * 
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -458,13 +458,15 @@ typedef enum _hreq_method
  * defines the class of response. The last two digits do not have any
  * categorization role. There are 5 values for the first digit: 
  *
- * - 1xx: Informational - Request received, continuing process
- * - 2xx: Success - The action was successfully received, understood, and
- *        accepted 
- * - 3xx: Redirection - Further action must be taken in order to complete the
- *        request
- * - 4xx: Client Error - The request contains bad syntax or cannot be fulfilled
- * - 5xx: Server Error - The server failed to fulfill an apparently valid request
+ * - @ref status_informational_sec - Request received, continuing process
+ * - @ref status_success_sec - The action was successfully received, understood,
+ *        and accepted 
+ * - @ref status_redirection_sec - Further action must be taken in order to
+ *        complete the request
+ * - @ref status_client_error_sec - The request contains bad syntax or cannot be
+ *        fulfilled
+ * - @ref status_server_error_sec - The server failed to fulfill an apparently
+ *        valid request
  *
  * The individual values of the numeric status codes defined for HTTP/1.1, and an
  * example set of corresponding Reason-Phrase's, are presented below. The reason
@@ -484,7 +486,7 @@ typedef enum _hreq_method
  * since that entity is likely to include human-readable information which will
  * explain the unusual status.
  *
- * \subsection status_informational_sec Informational 1xx
+ * @section status_informational_sec Informational 1xx
  *
  * This class of status code indicates a provisional response, consisting only
  * of the Status-Line and optional headers, and is terminated by an empty line.
@@ -503,12 +505,12 @@ typedef enum _hreq_method
  * "Expect: 100-continue" field when it forwards a request, then it need not
  * forward the corresponding 100 (Continue) response(s).)
  *
- * \subsection status_successful_sec Successful 2xx
+ * @section status_successful_sec Successful 2xx
  *
  * This class of status code indicates that the client's request was
  * successfully received, understood, and accepted.
  *
- * \subsection status_refirection_sec Redirection 3xx
+ * @section status_redirection_sec Redirection 3xx
  *
  * This class of status code indicates that further action needs to be taken by
  * the user agent in order to fulfill the request.  The action required MAY be
@@ -517,7 +519,7 @@ typedef enum _hreq_method
  * detect infinite redirection loops, since such loops generate network traffic
  * for each redirection.
  *
- * \subsection status_client_error_sec Client Error 4xx
+ * @section status_client_error_sec Client Error 4xx
  *
  * The 4xx class of status code is intended for cases in which the client seems
  * to have erred. Except when responding to a HEAD request, the server SHOULD
@@ -534,7 +536,7 @@ typedef enum _hreq_method
  * unacknowledged input buffers before they can be read and interpreted by the
  * HTTP application.
  *
- * \subsection status_server_error_sec Server Error 5xx
+ * @section status_server_error_sec Server Error 5xx
  *
  * Response status codes beginning with the digit "5" indicate cases in which
  * the server is aware that it has erred or is incapable of performing the
@@ -549,7 +551,7 @@ typedef enum _hreq_method
  * @see http://www.ietf.org/rfc/rfc2616.txt
  *
  */
-/*{*/
+/*@{*/
 
 /**
  *
@@ -1200,7 +1202,7 @@ typedef enum _hreq_method
  */
 #define HTTP_STATUS_505_REASON_PHRASE	"HTTP Version not supported"
 
-/*}*/
+/*@}*/
 
 /**
  *
diff --git a/nanohttp/nanohttp-request.h b/nanohttp/nanohttp-request.h
index 209ef9a..739c3c9 100755
--- a/nanohttp/nanohttp-request.h
+++ b/nanohttp/nanohttp-request.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-request.h,v 1.13 2006/12/10 12:23:45 m0gg Exp $
+ *  $Id: nanohttp-request.h,v 1.14 2006/12/11 08:13:19 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -34,7 +34,7 @@
  * @see http://www.ietf.org/rfc/rfc2616.txt
  *
  */
-/*{*/
+/*@{*/
 
 /**
  *
@@ -252,7 +252,7 @@
  */
 #define HEADER_USER_AGENT		"User-Agent"
 
-/*}*/
+/*@}*/
 
 #ifdef __NHTTP_INTERNAL
 struct request_statistics
diff --git a/nanohttp/nanohttp-response.h b/nanohttp/nanohttp-response.h
index b198128..ce2984b 100755
--- a/nanohttp/nanohttp-response.h
+++ b/nanohttp/nanohttp-response.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-response.h,v 1.13 2006/12/10 12:23:46 m0gg Exp $
+ *  $Id: nanohttp-response.h,v 1.14 2006/12/11 08:13:19 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -34,7 +34,7 @@
  * @see	http://www.ietf.org/rfc/rfc2616.txt
  *
  */
-/*{*/
+/*@{*/
 
 /**
  *
@@ -150,7 +150,7 @@
  */
 #define HEADER_WWW_AUTHENTICATE		"WWW-Authenticate"
 
-/*}*/
+/*@}*/
 
 /**
  *
diff --git a/nanohttp/nanohttp-server.h b/nanohttp/nanohttp-server.h
index 4205900..eb1f178 100644
--- a/nanohttp/nanohttp-server.h
+++ b/nanohttp/nanohttp-server.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-server.h,v 1.30 2006/12/10 19:21:07 m0gg Exp $
+ *  $Id: nanohttp-server.h,v 1.31 2006/12/11 08:13:19 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -38,7 +38,7 @@
  *
  * @page nanohttp_page nanoHTTP
  *
- * \section nanohttp_sec nanoHTTP
+ * @section nanohttp_sec nanoHTTP
  *
  * nanoHTTP is an embedded HTTP implementation. It comes with the following
  * features:
@@ -46,11 +46,11 @@
  * - attachments via MIME
  * - HTTPS support (SSL/TLS) using OpenSSL
  *
- * \section links_sec Howto to the nanoHTTP library
+ * @section links_sec Howto to the nanoHTTP library
  *
- * - \ref nanohttp_client_page
- * - \ref nanohttp_server_page
- * - \ref nanohttp_mime_page
+ * - @ref nanohttp_client_page
+ * - @ref nanohttp_server_page
+ * - @ref nanohttp_mime_page
  *
  * @author	Ferhat Ayaz
  * @author	Michael Rans
@@ -66,15 +66,15 @@
 
 /** @page nanohttp_server_page Howto write an HTTP server
  *
- * \section server_sec Table of contents
+ * @section server_sec Table of contents
  * 
- * - \ref init_sec
- * - \ref service_sec
- * - \ref running_sec
- * - \ref cleanup_sec
- * - \ref function_sec
+ * - @ref init_sec
+ * - @ref service_sec
+ * - @ref running_sec
+ * - @ref cleanup_sec
+ * - @ref function_sec
  *
- * \section init_sec Server initialization
+ * @section init_sec Server initialization
  *
  * @code
  * int main(int argc, char **argv)
@@ -89,7 +89,7 @@
  *   }
  * @endcode
  *
- * \section service_sec Service registration
+ * @section service_sec Service registration
  *
  * @code
  *   if ((status = httpd_register("/", root_service)) != H_OK)
@@ -131,7 +131,7 @@
  *   }
  * @endcode
  *
- * \section running_sec Running the server
+ * @section running_sec Running the server
  *
  * @code
  *   if ((status = httpd_run()) != H_OK)
@@ -143,7 +143,7 @@
  *   }
  * @endcode
  *
- * \section cleanup_sec Server cleanup
+ * @section cleanup_sec Server cleanup
  *
  * @code
  *   httpd_destroy();
@@ -152,7 +152,7 @@
  * }
  * @endcode
  *
- * \section function_seq Sample service function
+ * @section function_seq Sample service function
  *
  * @code
  * static void headers_service(httpd_conn_t *conn, struct hrequest_t *req)
@@ -191,7 +191,7 @@
 
 /**
  *
- * nanohttp command line flags
+ * nanoHTTP command line flags
  *
  */
 #define NHTTPD_ARG_PORT		"-NHTTPport"
diff --git a/nanohttp/nanohttp-socket.h b/nanohttp/nanohttp-socket.h
index 36f2c09..115defe 100644
--- a/nanohttp/nanohttp-socket.h
+++ b/nanohttp/nanohttp-socket.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-socket.h,v 1.37 2006/12/10 19:21:07 m0gg Exp $
+ *  $Id: nanohttp-socket.h,v 1.38 2006/12/11 08:13:19 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -27,7 +27,7 @@
 /** @defgroup socket_errors Socket errors
  *
  */
-/*{*/
+/*@{*/
 
 /**
  *
@@ -46,6 +46,8 @@
 #define HSOCKET_ERROR_NOT_INITIALIZED	(HSOCKET_ERROR + 9)
 #define HSOCKET_ERROR_IOCTL		(HSOCKET_ERROR + 10)
 
+/*@}*/
+
 /**
  *
  * @todo move the next two items to nanohttp-ssl.h
diff --git a/nanohttp/nanohttp-ssl.c b/nanohttp/nanohttp-ssl.c
index 46b90f1..4d3cb2c 100644
--- a/nanohttp/nanohttp-ssl.c
+++ b/nanohttp/nanohttp-ssl.c
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: nanohttp-ssl.c,v 1.36 2006/12/06 11:27:21 m0gg Exp $
+*  $Id: nanohttp-ssl.c,v 1.37 2006/12/11 08:13:19 m0gg Exp $
 *
 * CSOAP Project:  A http client/server library in C
 * Copyright (C) 2001-2005  Rochester Institute of Technology
@@ -84,6 +84,8 @@
 
 #include "nanohttp-ssl.h"
 
+#define CERT_SUBJECT	1
+
 static char *_hssl_certificate = NULL;
 static char *_hssl_certpass = NULL;
 static char *_hssl_ca_list = NULL;
diff --git a/nanohttp/nanohttp-ssl.h b/nanohttp/nanohttp-ssl.h
index cc8b7f7..aa5c781 100644
--- a/nanohttp/nanohttp-ssl.h
+++ b/nanohttp/nanohttp-ssl.h
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: nanohttp-ssl.h,v 1.25 2006/12/03 17:30:58 m0gg Exp $
+*  $Id: nanohttp-ssl.h,v 1.26 2006/12/11 08:13:19 m0gg Exp $
 *
 * CSOAP Project:  A http client/server library in C
 * Copyright (C) 2001-2005  Rochester Institute of Technology
@@ -31,12 +31,13 @@
  */
 #define NHTTPD_ARG_HTTPS	"-NHTTPS"
 
-
 /**
  *
- * SSL Errors
+ * @defgroup ssl_errors_group SSL Errors
  *
  */
+/*@{*/
+
 #define HSSL_ERROR			1700
 #define HSSL_ERROR_CA_LIST		(HSSL_ERROR + 10)
 #define HSSL_ERROR_CONTEXT		(HSSL_ERROR + 20)
@@ -46,6 +47,8 @@
 #define HSSL_ERROR_SERVER		(HSSL_ERROR + 60)
 #define HSSL_ERROR_CONNECT		(HSSL_ERROR + 70)
 
+/*@}*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -133,8 +136,6 @@ extern herror_t hssl_server_ssl(struct hsocket_t * sock);
  */
 extern void hssl_cleanup(struct hsocket_t * sock);
 
-#define CERT_SUBJECT	1
-
 /**
  *
  * Quick function for verifying a portion of the cert nid is any NID_ defined
diff --git a/nanohttp/nanohttp-url.h b/nanohttp/nanohttp-url.h
index 61342f5..6e72749 100644
--- a/nanohttp/nanohttp-url.h
+++ b/nanohttp/nanohttp-url.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-url.h,v 1.2 2006/12/10 19:21:07 m0gg Exp $
+ *  $Id: nanohttp-url.h,v 1.3 2006/12/11 08:13:19 m0gg Exp $
  * 
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -48,9 +48,6 @@ typedef enum _hprotocol
   PROTOCOL_HTTPS
 } hprotocol_t;
 
-#define URL_MAX_HOST_SIZE      120
-#define URL_MAX_CONTEXT_SIZE  1024
-
 /**
  *
  * The URL object. A representation of an URL like: