Documentation enhancements

2 files changed, 275 insertions, 44 deletions

diff --git a/nanohttp/nanohttp-common.h b/nanohttp/nanohttp-common.h
index dabdda6..324f3db 100644
--- a/nanohttp/nanohttp-common.h
+++ b/nanohttp/nanohttp-common.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-common.h,v 1.34 2006/11/25 15:06:58 m0gg Exp $
+ *  $Id: nanohttp-common.h,v 1.35 2006/11/25 15:38:10 m0gg Exp $
  * 
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -40,14 +40,105 @@
  *
  */
 
+/**
+ *
+ * The Cache-Control general-header field is used to specify directives that MUST
+ * be obeyed by all caching mechanisms along the request/response chain. The
+ * directives specify behavior intended to prevent caches from adversely
+ * interfering with the request or response. These directives typically override
+ * the default caching algorithms. Cache directives are unidirectional in that
+ * the presence of a directive in a request does not imply that the same
+ * directive is to be given in the response.
+ *
+ */
 #define HEADER_CACHE_CONTROL		"Cache-Control"
+
+/**
+ *
+ * The Connection general-header field allows the sender to specify options that
+ * are desired for that particular connection and MUST NOT be communicated by
+ * proxies over further connections.
+ *
+ */
 #define HEADER_CONNECTION		"Connection"
+
+/**
+ *
+ * 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.
+ *
+ * @see http://www.ietf.org/rfc/rfc822.txt,
+ *      http://www.ietf.org/rfc/rfc1123.txt
+ *
+ */
 #define HEADER_DATE			"Date"
+
+/**
+ *
+ * The Pragma general-header field is used to include implementation-specific
+ * directives that might apply to any recipient along the request/response chain.
+ * All pragma directives specify optional behavior from the viewpoint of the
+ * protocol; however, some systems MAY require that behavior be consistent with
+ * the directives.
+ *
+ */
 #define HEADER_PRAGMA			"Pragma"
+
+/**
+ *
+ * The Trailer general field value indicates that the given set of header fields
+ * is present in the trailer of a message encoded with chunked transfer-coding.
+ *
+ */
 #define HEADER_TRAILER			"Trailer"
+
+/**
+ *
+ * The Transfer-Encoding general-header field indicates what (if any) type of
+ * transformation has been applied to the message body in order to safely
+ * transfer it between the sender and the recipient. This differs from the
+ * content-coding in that the transfer-coding is a property of the message, not
+ * of the entity.
+ *
+ */
 #define HEADER_TRANSFER_ENCODING	"Transfer-Encoding"
+
+/**
+ *
+ * The Upgrade general-header allows the client to specify what additional
+ * communication protocols it supports and would like to use if the server finds
+ * it appropriate to switch protocols. The server MUST use the Upgrade header
+ * field within a 101 (Switching Protocols) response to indicate which
+ * protocol(s) are being switched.
+ *
+ */
 #define HEADER_UPGRADE			"Upgrade"
+
+/**
+ *
+ * The Via general-header field MUST be used by gateways and proxies to indicate
+ * the intermediate protocols and recipients between the user agent and the
+ * server on requests, and between the origin server and the client on responses.
+ * It is analogous to the "Received" field of RFC 822 and is intended to be used
+ * for tracking message forwards, avoiding request loops, and identifying the
+ * protocol capabilities of all senders along the request/response chain.
+ *
+ * @see http://www.ietf.org/rfc/rfc822.txt
+ *
+ */
 #define HEADER_VIA			"Via"
+
+/**
+ *
+ * The Warning general-header field is used to carry additional information about
+ * the status or transformation of a message which might not be reflected in the
+ * message. This information is typically used to warn about a possible lack of
+ * semantic transparency from caching operations or transformations applied to
+ * the entity body of the message.
+ *
+ */
 #define HEADER_WARNING			"Warning"
 
 /**
@@ -62,15 +153,115 @@
  * @see http://www.ietf.org/rfc/rfc2616.txt
  *
  */
+
+/**
+ *
+ * The Allow entity-header field lists the set of methods supported by the
+ * resource identified by the Request-URI. The purpose of this field is strictly
+ * to inform the recipient of valid methods associated with the resource. An
+ * Allow header field MUST be present in a 405 (Method Not Allowed) response.
+ *
+ */
 #define HEADER_ALLOW			"Allow"
+
+/**
+ *
+ * The Content-Encoding entity-header field is used as a modifier to the
+ * media-type. When present, its value indicates what additional content codings
+ * have been applied to the entity-body, and thus what decoding mechanisms must
+ * be applied in order to obtain the media-type referenced by the Content-Type
+ * header field. Content-Encoding is primarily used to allow a document to be
+ * compressed without losing the identity of its underlying media type.
+ *
+ */
 #define HEADER_CONTENT_ENCODING		"Content-Encoding"
+
+/**
+ *
+ * The Content-Language entity-header field describes the natural language(s) of
+ * the intended audience for the enclosed entity. Note that this might not be
+ * equivalent to all the languages used within the entity-body.
+ *
+ */
 #define HEADER_CONTENT_LANGUAGE		"Content-Language"
+
+/**
+ *
+ * The Content-Length entity-header field indicates the size of the entity-body,
+ * in decimal number of OCTETs, sent to the recipient or, in the case of the HEAD
+ * method, the size of the entity-body that would have been sent had the request
+ * been a GET.
+ *
+ */
 #define HEADER_CONTENT_LENGTH		"Content-Length"
+
+/**
+ *
+ * The Content-Location entity-header field MAY be used to supply the resource
+ * location for the entity enclosed in the message when that entity is accessible
+ * from a location separate from the requested resource's URI. A server SHOULD
+ * provide a Content-Location for the variant corresponding to the response
+ * entity; especially in the case where a resource has multiple entities
+ * associated with it, and those entities actually have separate locations by
+ * which they might be individually accessed, the server SHOULD provide a
+ * Content-Location for the particular variant which is returned.
+ *
+ */
 #define HEADER_CONTENT_LOCATION		"Content-Location"
+
+/**
+ *
+ * The Content-MD5 entity-header field, as defined in RFC 1864, is an MD5 digest
+ * of the entity-body for the purpose of providing an end-to-end message
+ * integrity check (MIC) of the entity-body. (Note: a MIC is good for detecting
+ * accidental modification of the entity-body in transit, but is not proof
+ * against malicious attacks.)
+ *
+ * @see http://www.ietf.org/rfc/rfc1864.txt
+ *
+ */
 #define HEADER_CONTENT_MD5		"Content-MD5"
+
+/**
+ *
+ * The Content-Range entity-header is sent with a partial entity-body to specify
+ * where in the full entity-body the partial body should be applied. Range units
+ * are defined in RFC 2616 section 3.12.
+ *
+ * @see http://www.ietf.org/rfc/rcf2616.txt
+ *
+ */
 #define HEADER_CONTENT_RANGE		"Content-Range"
+
+/**
+ *
+ * The Content-Type entity-header field indicates the media type of the
+ * entity-body sent to the recipient or, in the case of the HEAD method, the
+ * media type that would have been sent had the request been a GET.
+ *
+ */
 #define HEADER_CONTENT_TYPE		"Content-Type"
+
+/**
+ *
+ * The Expires entity-header field gives the date/time after which the response
+ * is considered stale. A stale cache entry may not normally be returned by a
+ * cache (either a proxy cache or a user agent cache) unless it is first
+ * validated with the origin server (or with an intermediate cache that has a
+ * fresh copy of the entity). See RFC 2616 section 13.2 for further discussion of
+ * the expiration model.
+ *
+ * @see http://www.ietf.org/rfc/rfc2616.txt
+ *
+ */
 #define HEADER_EXPIRES			"Expires"
+
+/**
+ *
+ * The Last-Modified entity-header field indicates the date and time at which the
+ * origin server believes the variant was last modified.
+ *
+ */
 #define HEADER_LAST_MODIFIED		"Last-Modified"
 
 /**
@@ -449,8 +640,8 @@ typedef struct _content_type
  * @param content_type_str the string representation of the content-type field in
  *        a HTTP header.
  *
- * @returns A newly created content_type_t object. Free this object with
- *          content_type_free();
+ * @return A newly created content_type_t object. Free this object with
+ *         content_type_free();
  *
  * @see content_type_free
  */
diff --git a/nanohttp/nanohttp-error.h b/nanohttp/nanohttp-error.h
index 57b6634..642d6a0 100644
--- a/nanohttp/nanohttp-error.h
+++ b/nanohttp/nanohttp-error.h
@@ -1,5 +1,5 @@
 /******************************************************************
- *  $Id: nanohttp-error.h,v 1.1 2006/11/25 15:06:58 m0gg Exp $
+ *  $Id: nanohttp-error.h,v 1.2 2006/11/25 15:38:10 m0gg Exp $
  * 
  * CSOAP Project:  A http client/server library in C
  * Copyright (C) 2003-2004  Ferhat Ayaz
@@ -28,60 +28,69 @@
 #define H_OK				0
 
 /* Socket errors */
-#define HSOCKET_ERROR_CREATE		1001
-#define HSOCKET_ERROR_GET_HOSTNAME	1002
-#define HSOCKET_ERROR_CONNECT		1003
-#define HSOCKET_ERROR_SEND		1004
-#define HSOCKET_ERROR_RECEIVE		1005
-#define HSOCKET_ERROR_BIND		1006
-#define HSOCKET_ERROR_LISTEN		1007
-#define HSOCKET_ERROR_ACCEPT		1008
-#define HSOCKET_ERROR_NOT_INITIALIZED	1009
-#define HSOCKET_ERROR_IOCTL		1010
-#define HSOCKET_ERROR_SSLCLOSE		1011
-#define HSOCKET_ERROR_SSLCTX		1011
+#define HSOCKET_ERROR			1000
+#define HSOCKET_ERROR_CREATE		(HSOCKET_ERROR + 1)
+#define HSOCKET_ERROR_GET_HOSTNAME	(HSOCKET_ERROR + 2)
+#define HSOCKET_ERROR_CONNECT		(HSOCKET_ERROR + 3)
+#define HSOCKET_ERROR_SEND		(HSOCKET_ERROR + 4)
+#define HSOCKET_ERROR_RECEIVE		(HSOCKET_ERROR + 5)
+#define HSOCKET_ERROR_BIND		(HSOCKET_ERROR + 6)
+#define HSOCKET_ERROR_LISTEN		(HSOCKET_ERROR + 7)
+#define HSOCKET_ERROR_ACCEPT		(HSOCKET_ERROR + 8)
+#define HSOCKET_ERROR_NOT_INITIALIZED	(HSOCKET_ERROR + 9)
+#define HSOCKET_ERROR_IOCTL		(HSOCKET_ERROR + 10)
+#define HSOCKET_ERROR_SSLCLOSE		(HSOCKET_ERROR + 11)
+#define HSOCKET_ERROR_SSLCTX		(HSOCKET_ERROR + 11)
 
 /* URL errors */
-#define URL_ERROR_UNKNOWN_PROTOCOL	1101
-#define URL_ERROR_NO_PROTOCOL		1102
-#define URL_ERROR_NO_HOST		1103
+#define URL_ERROR			1100
+#define URL_ERROR_UNKNOWN_PROTOCOL	(URL_ERROR + 1)
+#define URL_ERROR_NO_PROTOCOL		(URL_ERROR + 2)
+#define URL_ERROR_NO_HOST		(URL_ERROR + 3)
 
 /* Stream errors */
-#define STREAM_ERROR_INVALID_TYPE	1201
-#define STREAM_ERROR_SOCKET_ERROR	1202
-#define STREAM_ERROR_NO_CHUNK_SIZE	1203
-#define STREAM_ERROR_WRONG_CHUNK_SIZE	1204
+#define STREAM_ERROR			1200
+#define STREAM_ERROR_INVALID_TYPE	(STREAM_ERROR + 1)
+#define STREAM_ERROR_SOCKET_ERROR	(STREAM_ERROR + 2)
+#define STREAM_ERROR_NO_CHUNK_SIZE	(STREAM_ERROR + 3)
+#define STREAM_ERROR_WRONG_CHUNK_SIZE	(STREAM_ERROR + 4)
 
 /* MIME errors */
-#define MIME_ERROR_NO_BOUNDARY_PARAM	1301
-#define MIME_ERROR_NO_START_PARAM	1302
-#define MIME_ERROR_PARSE_ERROR		1303
-#define MIME_ERROR_NO_ROOT_PART		1304
-#define MIME_ERROR_NOT_MIME_MESSAGE	1305
+#define MIME_ERROR			1300
+#define MIME_ERROR_NO_BOUNDARY_PARAM	(MIME_ERROR + 1)
+#define MIME_ERROR_NO_START_PARAM	(MIME_ERROR + 2)
+#define MIME_ERROR_PARSE_ERROR		(MIME_ERROR + 3)
+#define MIME_ERROR_NO_ROOT_PART		(MIME_ERROR + 4)
+#define MIME_ERROR_NOT_MIME_MESSAGE	(MIME_ERROR + 5)
 
 /* General errors */
-#define GENERAL_INVALID_PARAM		1400
-#define GENERAL_HEADER_PARSE_ERROR	1401
+#define GENERAL_ERROR			1400
+#define GENERAL_INVALID_PARAM		(GENERAL_ERROR + 1)
+#define GENERAL_HEADER_PARSE_ERROR	(GENERAL_ERROR + 2)
 
 /* Thread errors */
-#define THREAD_BEGIN_ERROR		1500
+#define THREAD_ERROR			1500
+#define THREAD_BEGIN_ERROR		(THREAD_ERROR)
 
 /* XML Errors */
-#define XML_ERROR_EMPTY_DOCUMENT	1600
-#define XML_ERROR_PARSE			1601
+#define XML_ERROR			1600
+#define XML_ERROR_EMPTY_DOCUMENT	(XML_ERROR + 1)
+#define XML_ERROR_PARSE			(XML_ERROR + 2)
 
 /* SSL Errors */
-#define HSSL_ERROR_CA_LIST		1710
-#define HSSL_ERROR_CONTEXT		1720
-#define HSSL_ERROR_CERTIFICATE		1730
-#define HSSL_ERROR_PEM			1740
-#define HSSL_ERROR_CLIENT		1750
-#define HSSL_ERROR_SERVER		1760
-#define HSSL_ERROR_CONNECT		1770
+#define HSSL_ERROR			1700
+#define HSSL_ERROR_CA_LIST		(HSSL_ERROR + 10)
+#define HSSL_ERROR_CONTEXT		(HSSL_ERROR + 20)
+#define HSSL_ERROR_CERTIFICATE		(HSSL_ERROR + 30)
+#define HSSL_ERROR_PEM			(HSSL_ERROR + 40)
+#define HSSL_ERROR_CLIENT		(HSSL_ERROR + 50)
+#define HSSL_ERROR_SERVER		(HSSL_ERROR + 60)
+#define HSSL_ERROR_CONNECT		(HSSL_ERROR + 70)
 
 /* File errors */
-#define FILE_ERROR_OPEN			8000
-#define FILE_ERROR_READ			8001
+#define FILE_ERROR			8000
+#define FILE_ERROR_OPEN			(FILE_ERROR + 1)
+#define FILE_ERROR_READ			(FILE_ERROR + 2)
 
 typedef void *herror_t;
 
@@ -89,10 +98,41 @@ typedef void *herror_t;
 extern "C" {
 #endif
 
+/**
+ *
+ * Creates a new error struture.
+ *
+ * @see printf
+ *
+ */
 extern herror_t herror_new(const char *func, int errcode, const char *format, ...);
+
+/**
+ *
+ * Returns the code of the error.
+ *
+ */
 extern int herror_code(herror_t err);
-extern char *herror_func(herror_t err);
-extern char *herror_message(herror_t err);
+
+/**
+ *
+ * Returns the name of the function.
+ *
+ */
+extern const char *herror_func(herror_t err);
+
+/**
+ *
+ * Returns the error message.
+ *
+ */
+extern const char *herror_message(herror_t err);
+
+/**
+ *
+ * Frees the error structure.
+ *
+ */
 extern void herror_release(herror_t err);
 
 #ifdef __cplusplus