beautified and added comments all over

include/curl/curl.h

@@ -23,6 +23,30 @@
  * $Id$
  ***************************************************************************/
 
+/* If you have problems, all libcurl docs and details are found here:
+   http://curl.haxx.se/libcurl/
+*/
+
+/* This is the version number of the libcurl package from which this header
+   file origins: */
+#define LIBCURL_VERSION "7.10.6-pre3"
+
+/* This is the numeric version of the libcurl version number, meant for easier
+   parsing and comparions by programs. The LIBCURL_VERSION_NUM define will
+   always follow this syntax:
+
+         0xXXYYZZ
+
+   Where XX, YY and ZZ are the main version, release and patch numbers in
+   hexadecimal. All three numbers are always represented using two digits.  1.2
+   would appear as "0x010200" while version 9.11.7 appears as "0x090b07".
+
+   This 6-digit hexadecimal number does not show pre-release number, and it is
+   always a greater number in a more recent release. It makes comparisons with
+   greater than and less than work.
+*/
+#define LIBCURL_VERSION_NUM 0x070a06
+
 #include <stdio.h>
 /* The include stuff here is mainly for time_t! */
 #ifdef vms
@@ -51,8 +75,8 @@
 extern "C" {
 #endif
 
-/* stupid #define trick to preserve functionality with older code, but
+/* silly trick to preserve functionality with older code, but making it use
-   making it use our name space for the future */
+   our name space for the future */
 #define HttpPost curl_httppost
 
 struct curl_httppost {
@@ -61,15 +85,13 @@ struct curl_httppost {
   long namelength;                  /* length of name length */
   char *contents;                   /* pointer to allocated data contents */
   long contentslength;              /* length of contents field */
-
-  /* CMC: Added support for buffer uploads */
   char *buffer;                     /* pointer to allocated buffer contents */
   long bufferlength;                /* length of buffer field */
-
   char *contenttype;                /* Content-Type */
   struct curl_slist* contentheader; /* list of extra headers for this form */
-  struct curl_httppost *more; /* if one field name has more than one file, this
+  struct curl_httppost *more;       /* if one field name has more than one
-                                 link should link to following files */
+                                       file, this link should link to following
+                                       files */
   long flags;                       /* as defined below */
 #define HTTPPOST_FILENAME (1<<0)    /* specified content is a file name */
 #define HTTPPOST_READFILE (1<<1)    /* specified content is a file name */
@@ -77,13 +99,12 @@ struct curl_httppost {
                                        do not free in formfree */
 #define HTTPPOST_PTRCONTENTS (1<<3) /* contents is only stored pointer
                                        do not free in formfree */
-
-/* CMC: Added support for buffer uploads */
 #define HTTPPOST_BUFFER (1<<4)      /* upload file from buffer */
 #define HTTPPOST_PTRBUFFER (1<<5)   /* upload file from pointer contents */
 
-  char *showfilename; /* The file name to show. If not set, the actual
+  char *showfilename;               /* The file name to show. If not set, the
-                         file name will be used (if this is a file part) */
+                                       actual file name will be used (if this
+                                       is a file part) */
 };
 
 typedef int (*curl_progress_callback)(void *clientp,
@@ -213,13 +234,13 @@ typedef enum {
   CURLPROXY_SOCKS5 = 5
 } curl_proxytype;
 
-typedef enum {
+#define CURLAUTH_NONE         0       /* nothing */
-  CURLAUTH_BASIC  =       0, /* default */
+#define CURLAUTH_BASIC        (1<<0)  /* Basic (default) */
-  CURLAUTH_DIGEST =       1, /* Digest */
+#define CURLAUTH_DIGEST       (1<<1)  /* Digest */
-  CURLAUTH_GSSNEGOTIATE = 2, /* GSS-Negotiate */
+#define CURLAUTH_GSSNEGOTIATE (1<<2)  /* GSS-Negotiate */
-  CURLAUTH_NTLM =         3, /* NTLM */
+#define CURLAUTH_NTLM         (1<<3)  /* NTLM */
-  CURLAUTH_LASTKNOWN      /* never to be used */
+#define CURLAUTH_ANY ~0               /* all types set */
-} curl_httpauth;
+#define CURLAUTH_ANYSAFE (~CURLAUTH_BASIC)
 
 /* this was the error code 50 in 7.7.3 and a few earlier versions, this
    is no longer used by libcurl but is instead #defined here only to not
@@ -270,6 +291,12 @@ typedef enum {
 #define CINIT(name,type,number) CURLOPT_/**/name = type + number
 #endif
 
+/*
+ * This macro-mania below setups the CURLOPT_[what] enum, to be used with
+ * curl_easy_setopt(). The first argument in the CINIT() macro is the [what]
+ * word.
+ */
+
 typedef enum {
   CINIT(NOTHING, LONG, 0), /********* the first one is unused ************/
   
@@ -279,24 +306,19 @@ typedef enum {
   /* The full URL to get/put */
   CINIT(URL,  OBJECTPOINT, 2),
 
-  /* Port number to connect to, if other than default. Specify the CONF_PORT
+  /* Port number to connect to, if other than default. */
-     flag in the CURLOPT_FLAGS to activate this */
   CINIT(PORT, LONG, 3),
 
-  /* Name of proxy to use. Specify the CONF_PROXY flag in the CURLOPT_FLAGS to
+  /* Name of proxy to use. */
-     activate this */
   CINIT(PROXY, OBJECTPOINT, 4),
   
-  /* Name and password to use when fetching. Specify the CONF_USERPWD flag in
+  /* "name:password" to use when fetching. */
-     the CURLOPT_FLAGS to activate this */
   CINIT(USERPWD, OBJECTPOINT, 5),
 
-  /* Name and password to use with Proxy. Specify the CONF_PROXYUSERPWD 
+  /* "name:password" to use with proxy. */
-     flag in the CURLOPT_FLAGS to activate this */
   CINIT(PROXYUSERPWD, OBJECTPOINT, 6),
 
-  /* Range to get, specified as an ASCII string. Specify the CONF_RANGE flag
+  /* Range to get, specified as an ASCII string. */
-     in the CURLOPT_FLAGS to activate this */
   CINIT(RANGE, OBJECTPOINT, 7),
 
   /* not used */
@@ -417,7 +439,6 @@ typedef enum {
      as described elsewhere. */
   CINIT(WRITEINFO, OBJECTPOINT, 40),
 
-  /* Previous FLAG bits */
   CINIT(VERBOSE, LONG, 41),      /* talk a lot */
   CINIT(HEADER, LONG, 42),       /* throw the header out too */
   CINIT(NOPROGRESS, LONG, 43),   /* shut off the progress meter */
@@ -633,8 +654,9 @@ typedef enum {
      attempted before the good old traditional PORT command. */     
   CINIT(FTP_USE_EPRT, LONG, 106),
 
-  /* Set this to a curl_httpauth value to enable that particular authentication
+  /* Set this to a bitmask value to enable the particular authentications
-     method. Use this in combination with CURLOPT_USERPWD. */
+     methods you like. Use this in combination with CURLOPT_USERPWD.
+     Note that setting multiple bits may cause extra network round-trips. */
   CINIT(HTTPAUTH, LONG, 107),
 
   CURLOPT_LASTENTRY /* the last unused */
@@ -705,9 +727,9 @@ typedef enum {
 #endif
 
 
-/* These functions are in the libcurl, they're here for portable reasons and
+/* These functions are in libcurl, they're here for portable reasons and they
-   they are used by the 'curl' client. They really should be moved to some kind
+   are used by the 'curl' client. They really should be moved to some kind of
-   of "portability library" since it has nothing to do with file transfers and
+   "portability library" since it has nothing to do with file transfers and
    might be usable to other programs...
 
    NOTE: they return TRUE if the strings match *case insensitively*.
@@ -715,9 +737,12 @@ typedef enum {
 extern int (curl_strequal)(const char *s1, const char *s2);
 extern int (curl_strnequal)(const char *s1, const char *s2, size_t n);
 
-/* DEPRECATED function to build formdata */
+#ifdef CURL_OLDSTYLE
+/* DEPRECATED function to build formdata. Stop using this, it will cease
+   to exist. */
 int curl_formparse(char *, struct curl_httppost **,
                    struct curl_httppost **_post);
+#endif
 
 /* name is uppercase CURLFORM_<name> */
 #ifdef CFINIT
@@ -796,47 +821,122 @@ typedef enum {
   CURL_FORMADD_LAST /* last */
 } CURLFORMcode;
 
+/*
+ * NAME curl_formadd()
+ *
+ * DESCRIPTION
+ *
+ * Pretty advanved function for building multi-part formposts. Each invoke
+ * adds one part that together construct a full post. Then use
+ * CURLOPT_HTTPPOST to send it off to libcurl.
+ */
 CURLFORMcode curl_formadd(struct curl_httppost **httppost,
                           struct curl_httppost **last_post,
                           ...);
 
-/* cleanup a form: */
+/*
+ * NAME curl_formfree()
+ *
+ * DESCRIPTION
+ *
+ * Free a multipart formpost previously built with curl_formadd().
+ */
 void curl_formfree(struct curl_httppost *form);
 
-/* Unix and Win32 getenv function call, this returns a malloc()'ed string that
+/*
-   MUST be free()ed after usage is complete. */
+ * NAME curl_getenv()
+ *
+ * DESCRIPTION
+ *
+ * Returns a malloc()'ed string that MUST be curl_free()ed after usage is
+ * complete.
+ */
 char *curl_getenv(const char *variable);
 
-/* Returns a static ascii string of the libcurl version. */
+/*
+ * NAME curl_version()
+ *
+ * DESCRIPTION
+ *
+ * Returns a static ascii string of the libcurl version.
+ */
 char *curl_version(void);
 
-/* Escape and unescape URL encoding in strings. The functions return a new
+/*
- * allocated string or NULL if an error occurred.  */
+ * NAME curl_escape()
+ *
+ * DESCRIPTION
+ *
+ * Escapes URL strings (converts all letters consider illegal in URLs to their
+ * %XX versions). This function returns a new allocated string or NULL if an
+ * error occurred.
+ */
 char *curl_escape(const char *string, int length);
+
+/*
+ * NAME curl_unescape()
+ *
+ * DESCRIPTION
+ *
+ * Unescapes URL encoding in strings (converts all %XX codes to their 8bit
+ * versions). This function returns a new allocated string or NULL if an error
+ * occurred.
+ */
 char *curl_unescape(const char *string, int length);
-/* 20020912 WJM. Provide for a de-allocation in the same translation unit
+
-   that did the allocation. Added in libcurl 7.10 */
+/*
+ * NAME curl_free()
+ *
+ * DESCRIPTION
+ *
+ * Provided for de-allocation in the same translation unit that did the
+ * allocation. Added in libcurl 7.10
+ */
 void curl_free(void *p);
 
-/* curl_global_init() should be invoked exactly once for each application that
+/*
-   uses libcurl */
+ * NAME curl_global_init()
+ *
+ * DESCRIPTION
+ *
+ * curl_global_init() should be invoked exactly once for each application that
+ * uses libcurl
+ */
 CURLcode curl_global_init(long flags);
 
-/* curl_global_cleanup() should be invoked exactly once for each application
+/*
-   that uses libcurl */
+ * NAME curl_global_cleanup()
+ *
+ * DESCRIPTION
+ *
+ * curl_global_cleanup() should be invoked exactly once for each application
+ * that uses libcurl
+ */
 void curl_global_cleanup(void);
 
-/* This is the version number */
-#define LIBCURL_VERSION "7.10.6-pre1"
-#define LIBCURL_VERSION_NUM 0x070a06
-
 /* linked-list structure for the CURLOPT_QUOTE option (and other) */
 struct curl_slist {
   char *data;
   struct curl_slist *next;
 };
 
+/*
+ * NAME curl_slist_append()
+ *
+ * DESCRIPTION
+ *
+ * Appends a string to a linked list. If no list exists, it will be created
+ * first. Returns the new list, after appending.
+ */
 struct curl_slist *curl_slist_append(struct curl_slist *, const char *);
+
+/*
+ * NAME curl_slist_free_all()
+ *
+ * DESCRIPTION
+ *
+ * free a previously built curl_slist.
+ */
 void curl_slist_free_all(struct curl_slist *);
 
 /*
@@ -1004,8 +1104,18 @@ typedef struct {
 #define CURL_VERSION_KERBEROS4 (1<<1)
 #define CURL_VERSION_SSL       (1<<2)
 #define CURL_VERSION_LIBZ      (1<<3)
+#define CURL_VERSION_NTLM      (1<<4)
+#define CURL_VERSION_GSSNEGOTIATE (1<<5)
+#define CURL_VERSION_DEBUG     (1<<6) /* built with debug capabilities */
 
-/* returns a pointer to a static copy of the version info struct */
+/*
+ * NAME curl_version_info()
+ *
+ * DESCRIPTION
+ *
+ * This function returns a pointer to a static copy of the version info
+ * struct. See above.
+ */
 curl_version_info_data *curl_version_info(CURLversion);
 
 #ifdef  __cplusplus