added function headers and comments

lib/connect.c

@@ -104,6 +104,10 @@
 
 static bool verifyconnect(curl_socket_t sockfd);
 
+/*
+ * Curl_ourerrno() returns the errno (or equivalent) on this platform to
+ * hide platform specific for the function that calls this.
+ */
 int Curl_ourerrno(void)
 {
 #ifdef WIN32
@@ -113,13 +117,11 @@ int Curl_ourerrno(void)
 #endif
 }
 
-/*************************************************************************
- * Curl_nonblock
- *
- * Description:
- *  Set the socket to either blocking or non-blocking mode.
+/*
+ * Curl_nonblock() set the given socket to either blocking or non-blocking
+ * mode based on the 'nonblock' boolean argument. This function is highly
+ * portable.
  */
-
 int Curl_nonblock(curl_socket_t sockfd,    /* operate on this */
                   int nonblock   /* TRUE or FALSE */)
 {
@@ -177,12 +179,19 @@ int Curl_nonblock(curl_socket_t sockfd,    /* operate on this */
 }
 
 /*
- * waitconnect() returns:
+ * waitconnect() waits for a TCP connect on the given socket for the specified
+ * number if milliseconds. It returns:
  * 0    fine connect
  * -1   select() error
  * 1    select() timeout
- * 2    select() returned with an error condition
+ * 2    select() returned with an error condition fd_set
  */
+
+#define WAITCONN_CONNECTED     0
+#define WAITCONN_SELECT_ERROR -1
+#define WAITCONN_TIMEOUT       1
+#define WAITCONN_FDSET_ERROR   2
+
 static
 int waitconnect(curl_socket_t sockfd, /* socket */
                 long timeout_msec)
@@ -213,18 +222,18 @@ int waitconnect(curl_socket_t sockfd, /* socket */
   rc = select(sockfd+1, NULL, &fd, &errfd, &interval);
   if(-1 == rc)
     /* error, no connect here, try next */
-    return -1;
+    return WAITCONN_SELECT_ERROR;
   
   else if(0 == rc)
     /* timeout, no connect today */
-    return 1;
+    return WAITCONN_TIMEOUT;
 
   if(FD_ISSET(sockfd, &errfd))
     /* error condition caught */
-    return 2;
+    return WAITCONN_FDSET_ERROR;
 
   /* we have a connect! */
-  return 0;
+  return WAITCONN_CONNECTED;
 }
 
 static CURLcode bindlocal(struct connectdata *conn,

lib/easy.c

@@ -85,14 +85,16 @@
 #include "memdebug.h"
 #endif
 
-/* Silly win32 socket initialization functions */
-
 #if defined(WIN32) && !defined(__GNUC__) || defined(__MINGW32__)
+/* win32_cleanup() is for win32 socket cleanup functionality, the opposite
+   of win32_init() */
 static void win32_cleanup(void)
 {
   WSACleanup();
 }
 
+/* win32_init() performs win32 socket initialization to properly setup the
+   stack to allow networking */
 static CURLcode win32_init(void)
 {
   WORD wVersionRequested;  
@@ -126,23 +128,23 @@ static CURLcode win32_init(void)
     WSACleanup(); 
     return CURLE_FAILED_INIT; 
   }
+  /* The Windows Sockets DLL is acceptable. Proceed. */
   return CURLE_OK;
 }
-/* The Windows Sockets DLL is acceptable. Proceed. */ 
+
 #else
 /* These functions exist merely to prevent compiler warnings */
 static CURLcode win32_init(void) { return CURLE_OK; }
 static void win32_cleanup(void) { }
 #endif
 
-
 /* true globals -- for curl_global_init() and curl_global_cleanup() */
 static unsigned int  initialized = 0;
 static long          init_flags  = 0;
 
 /**
- * Globally initializes cURL given a bitwise set of 
- * the different features to initialize.
+ * curl_global_init() globally initializes cURL given a bitwise set of the
+ * different features of what to initialize.
  */
 CURLcode curl_global_init(long flags)
 {
@@ -168,8 +170,8 @@ CURLcode curl_global_init(long flags)
 }
 
 /**
- * Globally cleanup cURL, uses the value of "init_flags" to determine
- * what needs to be cleaned up and what doesn't
+ * curl_global_cleanup() globally cleanups cURL, uses the value of
+ * "init_flags" to determine what needs to be cleaned up and what doesn't.
  */
 void curl_global_cleanup(void)
 {
@@ -192,6 +194,10 @@ void curl_global_cleanup(void)
   init_flags  = 0;
 }
 
+/*
+ * curl_easy_init() is the external interface to alloc, setup and init an
+ * easy handle that is returned. If anything goes wrong, NULL is returned.
+ */
 CURL *curl_easy_init(void)
 {
   CURLcode res;
@@ -213,6 +219,10 @@ CURL *curl_easy_init(void)
   return data;
 }
 
+/* 
+ * curl_easy_setopt() is the external interface for setting options on an
+ * easy handle.
+ */
 typedef int (*func_T)(void);
 CURLcode curl_easy_setopt(CURL *curl, CURLoption tag, ...)
 {
@@ -257,6 +267,10 @@ CURLcode curl_easy_setopt(CURL *curl, CURLoption tag, ...)
   return ret;
 }
 
+/*
+ * curl_easy_perform() is the external interface that performs a transfer
+ * previously setup.
+ */
 CURLcode curl_easy_perform(CURL *curl)
 {
   struct SessionHandle *data = (struct SessionHandle *)curl;
@@ -285,6 +299,10 @@ CURLcode curl_easy_perform(CURL *curl)
   return Curl_perform(data);
 }
 
+/*
+ * curl_easy_cleanup() is the external interface to cleaning/freeing the given
+ * easy handle.
+ */
 void curl_easy_cleanup(CURL *curl)
 {
   struct SessionHandle *data = (struct SessionHandle *)curl;
@@ -296,6 +314,10 @@ void curl_easy_cleanup(CURL *curl)
   Curl_close(data);
 }
 
+/*
+ * curl_easy_getinfo() is an external interface that allows an app to retrieve
+ * information from a performed transfer and similar.
+ */
 CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ...)
 {
   va_list arg;
@@ -308,6 +330,11 @@ CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ...)
   return Curl_getinfo(data, info, paramp);
 }
 
+/*
+ * curl_easy_duphandle() is an external interface to allow duplication of a
+ * given input easy handle. The returned handle will be a new working handle
+ * with all options set exactly as the input source handle.
+ */
 CURL *curl_easy_duphandle(CURL *incurl)
 {
   struct SessionHandle *data=(struct SessionHandle *)incurl;