Documentation enhancements

5 files changed, 164 insertions, 25 deletions

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