Documentation enhancements

8 files changed, 196 insertions, 51 deletions

diff --git a/README.ssl b/README.ssl
index 1c9b138..3d462c7 100644
--- a/README.ssl
+++ b/README.ssl
@@ -1,4 +1,4 @@
-$Id: README.ssl,v 1.2 2006/11/29 12:47:44 m0gg Exp $
+$Id: README.ssl,v 1.3 2006/12/10 12:23:40 m0gg Exp $
 ===============================================================================
 
 How to use SSL with nanoHTTP/cSOAP
@@ -81,7 +81,7 @@ commandline versions.
   - hssl_set_certpass(const char *pass)
   - hssl_set_ca(const char *CAfile)
 
-NOTE: If you use this functions an specify the commandline arguments, thenn the
+NOTE: If you use this functions an specify the commandline arguments, then the
 commandline arguments take precedence.
 
 6. What else?
diff --git a/examples/nanohttp/http_server.c b/examples/nanohttp/http_server.c
index 37ed073..a00c982 100644
--- a/examples/nanohttp/http_server.c
+++ b/examples/nanohttp/http_server.c
@@ -1,5 +1,5 @@
 /******************************************************************
-*  $Id: http_server.c,v 1.11 2006/12/02 21:50:47 m0gg Exp $
+*  $Id: http_server.c,v 1.12 2006/12/10 12:23:45 m0gg Exp $
 *
 * CSOAP Project:  A http client/server library in C (example)
 * Copyright (C) 2003  Ferhat Ayaz
@@ -142,45 +142,51 @@ int main(int argc, char **argv)
   herror_t status;
   hlog_set_level(HLOG_INFO);
 
-  if (httpd_init(argc, argv)) {
-
+  if (httpd_init(argc, argv))
+  {
     fprintf(stderr, "Cannot init httpd\n");
-    return 1;
+    httpd_destroy();
+    exit(1);
   }
 
-  if ((status = httpd_register("/", root_service)) != H_OK) {
-
+  if ((status = httpd_register("/", root_service)) != H_OK)
+  {
     fprintf(stderr, "Cannot register service (%s)\n", herror_message(status));
     herror_release(status);
-    return 1;
+    httpd_destroy();
+    exit(1);
   }
 
-  if ((status = httpd_register_secure("/secure", secure_service, simple_authenticator)) != H_OK) {
-
+  if ((status = httpd_register_secure("/secure", secure_service, simple_authenticator)) != H_OK)
+  {
     fprintf(stderr, "Cannot register secure service (%s)\n", herror_message(status));
     herror_release(status);
-    return 1;
+    httpd_destroy();
+    exit(1);
   }
 
-  if ((status = httpd_register("/headers", headers_service)) != H_OK) {
-
+  if ((status = httpd_register("/headers", headers_service)) != H_OK)
+  {
     fprintf(stderr, "Cannot register headers service (%s)\n", herror_message(status));
     herror_release(status);
-    return 1;
+    httpd_destroy();
+    exit(1);
   }
 
-  if ((status = httpd_register_default("/error", default_service)) != H_OK) {
-
+  if ((status = httpd_register_default("/error", default_service)) != H_OK)
+  {
     fprintf(stderr, "Cannot register default service (%s)\n", herror_message(status));
     herror_release(status);
-    return 1;
+    httpd_destroy();
+    exit(1);
   }
 
-  if (httpd_run()) {
-
-    fprintf(stderr, "Cannot run httpd\n");
+  if ((status = httpd_run()) != H_OK)
+  {
+    fprintf(stderr, "Cannot run httpd (%s)\n", herror_message(status));
     herror_release(status);
-    return 1;
+    httpd_destroy();
+    exit(1);
   }
 
   httpd_destroy();
diff --git a/libcsoap/soap-server.h b/libcsoap/soap-server.h
index f61d749..e858db9 100644
--- a/libcsoap/soap-server.h
+++ b/libcsoap/soap-server.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: soap-server.h,v 1.18 2006/12/09 09:57:38 m0gg Exp $
+ *  $Id: soap-server.h,v 1.19 2006/12/10 12:23:45 m0gg Exp $
  *
  * CSOAP Project:  A SOAP client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -37,10 +37,10 @@
  * @section seq_features Features
  *
  * - different transport services
- *   - @ref nanoHTTP (HTTP including SSL)
+ *   - @ref nanohttp_page (HTTP including SSL)
  *   - client/server UDP transport service (multicast)
  * - attachments via MIME
- * - message based security (encryption/signation)
+ * - message based security (XML encryption/signation)
  * - automatic generation of WS-Inspection
  *
  * @author	Ferhat Ayaz
@@ -58,7 +58,7 @@
 
 /** @file
  *
- * @version	$Revision: 1.18 $
+ * @version	$Revision: 1.19 $
  *
  */
 
diff --git a/nanohttp/nanohttp-client.h b/nanohttp/nanohttp-client.h
index 7759241..eaab46d 100644
--- a/nanohttp/nanohttp-client.h
+++ b/nanohttp/nanohttp-client.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-client.h,v 1.32 2006/12/09 09:04:16 m0gg Exp $
+ *  $Id: nanohttp-client.h,v 1.33 2006/12/10 12:23:45 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -34,9 +34,9 @@
 #include <nanohttp/nanohttp-logging.h>
 #endif
 
-/** @file
+/** @page nanohttp_client Howto write an HTTP client
  *
- * \section client_sec Writing an HTTP client using nanoHTTP
+ * \section client_sec Table of contents
  *
  * - Client initialization
  * - Connection initialization
diff --git a/nanohttp/nanohttp-common.h b/nanohttp/nanohttp-common.h
index dd60473..2356259 100644
--- a/nanohttp/nanohttp-common.h
+++ b/nanohttp/nanohttp-common.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-common.h,v 1.40 2006/12/09 09:04:16 m0gg Exp $
+ *  $Id: nanohttp-common.h,v 1.41 2006/12/10 12:23:45 m0gg Exp $
  * 
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -70,11 +70,12 @@
  *
  * The Date general-header field represents the date and time at which the
  * message was originated, having the same semantics as orig-date in RFC 822.
- * The field value is an HTTP-date, as described in section 3.3.1; it MUST be
- * sent in RFC 1123 [8]-date format.
+ * The field value is an HTTP-date, as described in RDF 2616 section 3.3.1; it
+ * MUST be sent in RFC 1123 date format.
  *
- * @see http://www.ietf.org/rfc/rfc822.txt,
- *      http://www.ietf.org/rfc/rfc1123.txt
+ * @see http://www.ietf.org/rfc/rfc822.txt
+ * @see http://www.ietf.org/rfc/rfc1123.txt
+ * @see http://www.ietf.org/rfc/rfc2616.txt
  *
  */
 #define HEADER_DATE			"Date"
@@ -152,7 +153,7 @@
  * Entity-header fields define metainformation about the entity-body or, if no
  * body is present, about the resource identified by the request. Some of this
  * metainformation is OPTIONAL; some might be REQUIRED by portions of this
- * specification. (see RFC2616 7.1)
+ * specification. (see RFC 2616 section 7.1)
  *
  * @see http://www.ietf.org/rfc/rfc2616.txt
  *
diff --git a/nanohttp/nanohttp-request.h b/nanohttp/nanohttp-request.h
index 3f6afba..209ef9a 100755
--- a/nanohttp/nanohttp-request.h
+++ b/nanohttp/nanohttp-request.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-request.h,v 1.12 2006/11/26 20:13:05 m0gg Exp $
+ *  $Id: nanohttp-request.h,v 1.13 2006/12/10 12:23:45 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -24,9 +24,7 @@
 #ifndef __nhttp_request_h
 #define __nhttp_request_h
 
-/** @file
- *
- * Request Header Fields
+/** @defgroup request_header_fields Request Header Fields
  *
  * The request-header fields allow the client to pass additional information
  * about the request, and about the client itself, to the server. These fields
@@ -36,6 +34,7 @@
  * @see http://www.ietf.org/rfc/rfc2616.txt
  *
  */
+/*{*/
 
 /**
  *
@@ -100,8 +99,8 @@
  * address SHOULD be machine-usable, as defined by "mailbox" in RFC 822 as
  * updated by RFC 1123.
  *
- * @see http://www.ietf.org/rfc/rfc1123.txt,
- *      http://www.ietf.org/rfc/rfc822.txt
+ * @see http://www.ietf.org/rfc/rfc1123.txt
+ * @see http://www.ietf.org/rfc/rfc822.txt
  *
  */
 #define HEADER_FROM			"From"
@@ -253,6 +252,8 @@
  */
 #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 459a814..b198128 100755
--- a/nanohttp/nanohttp-response.h
+++ b/nanohttp/nanohttp-response.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-response.h,v 1.12 2006/12/09 09:27:11 m0gg Exp $
+ *  $Id: nanohttp-response.h,v 1.13 2006/12/10 12:23:46 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -24,18 +24,17 @@
 #ifndef __nanohttp_response_h
 #define __nanohttp_response_h
 
-/** @file
- *
- * \section Response Header Fields
+/** @defgroup response_header_fields Response Header Fields
  *
  * The response-header fields allow the server to pass additional information
  * about the response which cannot be placed in the Status-Line. These header
  * fields give information about the server and about further access to the
- * resource identified by the Request-URI. (see RFC2616)
+ * resource identified by the Request-URI. (see RFC 2616)
  *
  * @see	http://www.ietf.org/rfc/rfc2616.txt
  *
  */
+/*{*/
 
 /**
  *
@@ -151,6 +150,8 @@
  */
 #define HEADER_WWW_AUTHENTICATE		"WWW-Authenticate"
 
+/*}*/
+
 /**
  *
  * HTTP response object
diff --git a/nanohttp/nanohttp-server.h b/nanohttp/nanohttp-server.h
index c02e0cf..ebea33f 100644
--- a/nanohttp/nanohttp-server.h
+++ b/nanohttp/nanohttp-server.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-server.h,v 1.28 2006/12/09 09:57:38 m0gg Exp $
+ *  $Id: nanohttp-server.h,v 1.29 2006/12/10 12:23:46 m0gg Exp $
  *
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003  Ferhat Ayaz
@@ -36,23 +36,159 @@
 
 /**
  *
- * @page nanoHTTP nanoHTTP
+ * @page nanohttp_page nanoHTTP
  *
  * \section nanohttp_sec nanoHTTP
  *
  * nanoHTTP is an embedded HTTP implementation. It comes with the following
  * features:
- * - client/server HTTP engnine
+ * - client/server HTTP engine
  * - attachments via MIME
- * - HTTPS (SSL/TLS) via OpenSSL
+ * - HTTPS support (SSL/TLS) using OpenSSL
  *
- * @version 1.2
+ * \section links_sec Howto to the nanoHTTP library
+ *
+ * - \ref nanohttp_client
+ * - \ref nanohttp_server
+ * - \ref nanohttp_mime
+ *
+ * @author	Ferhat Ayaz
+ * @author	Michael Rans
+ * @author	Matt Campbell
+ * @author	Heiko Ronsdorf
+ *
+ * @version	1.2
  *
  * @see http://www.ietf.org/rfc/rfc2616.txt
  * @see http://www.openssl.org
  *
  */
 
+/** @page nanohttp_server Howto write an HTTP server
+ *
+ * \section server_sec Table of contents
+ * 
+ * - \ref init_sec
+ * - \ref service_sec
+ * - \ref running_sec
+ * - \ref cleanup_sec
+ * - \ref function_sec
+ *
+ * \section init_sec Server initialization
+ *
+ * @code
+ * int main(int argc, char **argv)
+ * {
+ *   herror_t status;
+ *   hlog_set_level(HLOG_INFO);
+ *
+ *   if (httpd_init(argc, argv))
+ *   {
+ *     fprintf(stderr, "Cannot init httpd\n");
+ *     exit(1);
+ *   }
+ * @code
+ *
+ * \section service_sec Service registration
+ *
+ * @code
+ *   if ((status = httpd_register("/", root_service)) != H_OK)
+ *   {
+ *     fprintf(stderr, "Cannot register service (%s)\n", herror_message(status));
+ *     herror_release(status);
+ *     httpd_destroy();
+ *     exit(1);
+ *   }
+ * @code
+ *
+ * @code
+ *   if ((status = httpd_register_secure("/secure", secure_service, simple_authenticator)) != H_OK)
+ *   {
+ *     fprintf(stderr, "Cannot register secure service (%s)\n", herror_message(status));
+ *     herror_release(status);
+ *     httpd_destroy();
+ *     exit(1);
+ *   }
+ * @code
+ *
+ * @code
+ *   if ((status = httpd_register("/headers", headers_service)) != H_OK)
+ *   {
+ *     fprintf(stderr, "Cannot register headers service (%s)\n", herror_message(status));
+ *     herror_release(status);
+ *     httpd_destroy();
+ *     exit(1);
+ *   }
+ * @code
+ *
+ * @code
+ *   if ((status = httpd_register_default("/error", default_service)) != H_OK)
+ *   {
+ *     fprintf(stderr, "Cannot register default service (%s)\n", herror_message(status));
+ *     herror_release(status);
+ *     httpd_destroy();
+ *     exit(1);
+ *   }
+ * @code
+ *
+ * \section running_sec Running the server
+ *
+ * @code
+ *   if ((status = httpd_run()) != H_OK)
+ *   {
+ *     fprintf(stderr, "Cannot run httpd (%s)\n", herror_message(status));
+ *     herror_release(status);
+ *     httpd_destroy();
+ *     exit(1);
+ *   }
+ * @code
+ *
+ * \section cleanup_sec Server cleanup
+ *
+ * @code
+ *   httpd_destroy();
+ *
+ *   exit(0);
+ * }
+ * @code
+ *
+ * \section function_seq Sample service function
+ *
+ * @code
+ * static void headers_service(httpd_conn_t *conn, struct hrequest_t *req)
+ * {
+ *   hpair_t *walker;
+ *
+ *   httpd_send_header(conn, 200, HTTP_STATUS_200_REASON_PHRASE);
+ *   http_output_stream_write_string(conn->out,
+ *     "<html>"
+ *       "<head>"
+ *         "<title>Request headers</title>"
+ *       "</head>"
+ *       "<body>"
+ *         "<h1>Request headers</h1>"
+ *         "<ul>");
+ *
+ *   for (walker=req->header; walker; walker=walker->next)
+ *   {
+ *     http_output_stream_write_string(conn->out, "<li>");
+ *     http_output_stream_write_string(conn->out, walker->key);
+ *     http_output_stream_write_string(conn->out, " = ");
+ *     http_output_stream_write_string(conn->out, walker->value);
+ *     http_output_stream_write_string(conn->out, "</li>");
+ *   }
+ *
+ *   http_output_stream_write_string(conn->out,
+ *         "</ul>"
+ *       "</body>"
+ *     "</html>");
+ *
+ *   return;
+ * }
+ * @code
+ *
+ */
+
 /**
  *
  * nanohttp command line flags