Revert "cleanup: general removal of TODO (and similar) comments"

This reverts commit 64e959ffe37c436503f9fed1ce2d6ee6ae50bd9a.

Feedback-by: Dan Fandrich
URL: http://curl.haxx.se/mail/lib-2015-11/0062.html

19 files changed, 97 insertions, 26 deletions

diff --git a/lib/asyn-ares.c b/lib/asyn-ares.c
index 080010222..98ecdfd71 100644
--- a/lib/asyn-ares.c
+++ b/lib/asyn-ares.c
@@ -416,6 +416,7 @@ CURLcode Curl_resolver_wait_resolv(struct connectdata *conn,
   if(result)
     /* close the connection, since we can't return failure here without
        cleaning up this connection properly.
+       TODO: remove this action from here, it is not a name resolver decision.
     */
     connclose(conn, "c-ares resolve failed");
 
diff --git a/lib/curl_memory.h b/lib/curl_memory.h
index 73bbe3fca..bc744ccd8 100644
--- a/lib/curl_memory.h
+++ b/lib/curl_memory.h
@@ -7,7 +7,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al.
  *
  * This software is licensed as described in the file COPYING, which
  * you should have received as part of this distribution. The terms
@@ -39,7 +39,7 @@
  *
  * File lib/strdup.c is an exception, given that it provides a strdup
  * clone implementation while using malloc. Extra care needed inside
- * this one.
+ * this one. TODO: revisit this paragraph and related code.
  *
  * The need for curl_memory.h inclusion is due to libcurl's feature
  * of allowing library user to provide memory replacement functions,
diff --git a/lib/easy.c b/lib/easy.c
index f90dd1694..48961d6da 100644
--- a/lib/easy.c
+++ b/lib/easy.c
@@ -646,7 +646,7 @@ static CURLcode wait_or_timeout(struct Curl_multi *multi, struct events *ev)
       return CURLE_RECV_ERROR;
 
     if(mcode)
-      return CURLE_URL_MALFORMAT;
+      return CURLE_URL_MALFORMAT; /* TODO: return a proper error! */
 
     /* we don't really care about the "msgs_in_queue" value returned in the
        second argument */
diff --git a/lib/ftp.c b/lib/ftp.c
index bf35ed7da..21db56c8e 100644
--- a/lib/ftp.c
+++ b/lib/ftp.c
@@ -3659,7 +3659,7 @@ static CURLcode ftp_do_more(struct connectdata *conn, int *completep)
   if(!conn->bits.tcpconnect[SECONDARYSOCKET]) {
     if(conn->tunnel_state[SECONDARYSOCKET] == TUNNEL_CONNECT) {
       /* As we're in TUNNEL_CONNECT state now, we know the proxy name and port
-         aren't used so we blank their arguments. */
+         aren't used so we blank their arguments. TODO: make this nicer */
       result = Curl_proxyCONNECT(conn, SECONDARYSOCKET, NULL, 0, FALSE);
 
       return result;
diff --git a/lib/http.c b/lib/http.c
index eaa5f949c..0ed9c9844 100644
--- a/lib/http.c
+++ b/lib/http.c
@@ -2047,7 +2047,10 @@ CURLcode Curl_http(struct connectdata *conn, bool *done)
       ptr = strstr(url, conn->host.dispname);
       if(ptr) {
         /* This is where the display name starts in the URL, now replace this
-           part with the encoded name. */
+           part with the encoded name. TODO: This method of replacing the host
+           name is rather crude as I believe there's a slight risk that the
+           user has entered a user name or password that contain the host name
+           string. */
         size_t currlen = strlen(conn->host.dispname);
         size_t newlen = strlen(conn->host.name);
         size_t urllen = strlen(url);
@@ -3329,6 +3332,7 @@ CURLcode Curl_http_readwrite_headers(struct SessionHandle *data,
           conn->httpversion = 11; /* For us, RTSP acts like HTTP 1.1 */
         }
         else {
+          /* TODO: do we care about the other cases here? */
           nc = 0;
         }
       }
@@ -3559,6 +3563,7 @@ CURLcode Curl_http_readwrite_headers(struct SessionHandle *data,
         }
 
         if(k->auto_decoding)
+          /* TODO: we only support the first mentioned compression for now */
           break;
 
         if(checkprefix("identity", start)) {
diff --git a/lib/http2.c b/lib/http2.c
index df6cb0c73..246b64ac5 100644
--- a/lib/http2.c
+++ b/lib/http2.c
@@ -75,6 +75,8 @@ static int http2_perform_getsock(const struct connectdata *conn,
   int bitmap = GETSOCK_BLANK;
   (void)numsocks;
 
+  /* TODO We should check underlying socket state if it is SSL socket
+     because of renegotiation. */
   sock[0] = conn->sock[FIRSTSOCKET];
 
   if(nghttp2_session_want_read(c->h2))
@@ -574,7 +576,8 @@ static int on_data_chunk_recv(nghttp2_session *session, uint8_t flags,
 
   /* if we receive data for another handle, wake that up */
   if(conn->data != data_s)
-    Curl_expire(data_s, 1);
+    Curl_expire(data_s, 1); /* TODO: fix so that this can be set to 0 for
+                               immediately? */
 
   DEBUGF(infof(data_s, "%zu data received for stream %u "
                "(%zu left in buffer %p, total %zu)\n",
diff --git a/lib/imap.c b/lib/imap.c
index bb0c5190f..a7409f704 100644
--- a/lib/imap.c
+++ b/lib/imap.c
@@ -842,7 +842,7 @@ static CURLcode imap_state_servergreet_resp(struct connectdata *conn,
 
   if(imapcode != 'O') {
     failf(data, "Got unexpected imap-server response");
-    result = CURLE_FTP_WEIRD_SERVER_REPLY;
+    result = CURLE_FTP_WEIRD_SERVER_REPLY; /* TODO: fix this code */
   }
   else
     result = imap_perform_capability(conn);
@@ -1033,7 +1033,7 @@ static CURLcode imap_state_list_resp(struct connectdata *conn, int imapcode,
     line[len] = '\0';
   }
   else if(imapcode != 'O')
-    result = CURLE_QUOTE_ERROR;
+    result = CURLE_QUOTE_ERROR; /* TODO: Fix error code */
   else
     /* End of DO phase */
     state(conn, IMAP_STOP);
@@ -1105,7 +1105,7 @@ static CURLcode imap_state_fetch_resp(struct connectdata *conn, int imapcode,
   if(imapcode != '*') {
     Curl_pgrsSetDownloadSize(data, -1);
     state(conn, IMAP_STOP);
-    return CURLE_REMOTE_FILE_NOT_FOUND;
+    return CURLE_REMOTE_FILE_NOT_FOUND; /* TODO: Fix error code */
   }
 
   /* Something like this is received "* 1 FETCH (BODY[TEXT] {2021}\r" so parse
@@ -1174,7 +1174,7 @@ static CURLcode imap_state_fetch_resp(struct connectdata *conn, int imapcode,
   else {
     /* We don't know how to parse this line */
     failf(pp->conn->data, "Failed to parse FETCH response.");
-    result = CURLE_FTP_WEIRD_SERVER_REPLY;
+    result = CURLE_FTP_WEIRD_SERVER_REPLY; /* TODO: fix this code */
   }
 
   /* End of DO phase */
@@ -1193,7 +1193,7 @@ static CURLcode imap_state_fetch_final_resp(struct connectdata *conn,
   (void)instate; /* No use for this yet */
 
   if(imapcode != 'O')
-    result = CURLE_FTP_WEIRD_SERVER_REPLY;
+    result = CURLE_FTP_WEIRD_SERVER_REPLY; /* TODO: Fix error code */
   else
     /* End of DONE phase */
     state(conn, IMAP_STOP);
@@ -1262,7 +1262,7 @@ static CURLcode imap_state_search_resp(struct connectdata *conn, int imapcode,
     line[len] = '\0';
   }
   else if(imapcode != 'O')
-    result = CURLE_QUOTE_ERROR;
+    result = CURLE_QUOTE_ERROR; /* TODO: Fix error code */
   else
     /* End of DO phase */
     state(conn, IMAP_STOP);
@@ -1506,10 +1506,10 @@ static CURLcode imap_done(struct connectdata *conn, CURLcode status,
 
     /* Run the state-machine
 
-       This _really_ should be using the imap_multi_statemach function but we
-       have no general support for non-blocking DONE operations. Neither in
-       the multi state machine and there are Curl_done() invokes on several
-       places in the code!
+       TODO: when the multi interface is used, this _really_ should be using
+       the imap_multi_statemach function but we have no general support for
+       non-blocking DONE operations, not in the multi state machine and with
+       Curl_done() invokes on several places in the code!
     */
     if(!result)
       result = imap_block_statemach(conn);
diff --git a/lib/openldap.c b/lib/openldap.c
index 862813b41..e479ebc75 100644
--- a/lib/openldap.c
+++ b/lib/openldap.c
@@ -176,7 +176,9 @@ static CURLcode ldap_setup_connection(struct connectdata *conn)
   li->proto = proto;
   conn->proto.generic = li;
   connkeep(conn, "OpenLDAP default");
-
+  /* TODO:
+   * - provide option to choose SASL Binds instead of Simple
+   */
   return CURLE_OK;
 }
 
@@ -479,6 +481,8 @@ static ssize_t ldap_recv(struct connectdata *conn, int sockindex, char *buf,
     lr->nument++;
     rc = ldap_get_dn_ber(li->ld, ent, &ber, &bv);
     if(rc < 0) {
+      /* TODO: verify that this is really how this return code should be
+         handled */
       *err = CURLE_RECV_ERROR;
       return -1;
     }
diff --git a/lib/rtsp.c b/lib/rtsp.c
index d190eef9f..f8e6b23dc 100644
--- a/lib/rtsp.c
+++ b/lib/rtsp.c
@@ -42,6 +42,16 @@
 #include "curl_memory.h"
 #include "memdebug.h"
 
+/*
+ * TODO (general)
+ *  -incoming server requests
+ *      -server CSeq counter
+ *  -digest authentication
+ *  -connect thru proxy
+ *  -pipelining?
+ */
+
+
 #define RTP_PKT_CHANNEL(p)   ((int)((unsigned char)((p)[1])))
 
 #define RTP_PKT_LENGTH(p)  ((((int)((unsigned char)((p)[2]))) << 8) | \
@@ -212,6 +222,7 @@ static CURLcode rtsp_done(struct connectdata *conn,
     else if(data->set.rtspreq == RTSPREQ_RECEIVE &&
             (conn->proto.rtspc.rtp_channel == -1)) {
       infof(data, "Got an RTP Receive with a CSeq of %ld\n", CSeq_recv);
+      /* TODO CPC: Server -> Client logic here */
     }
   }
 
@@ -317,6 +328,8 @@ static CURLcode rtsp_do(struct connectdata *conn, bool *done)
     return CURLE_BAD_FUNCTION_ARGUMENT;
   }
 
+  /* TODO: proxy? */
+
   /* Stream URI. Default to server '*' if not specified */
   if(data->set.str[STRING_RTSP_STREAM_URI]) {
     p_stream_uri = data->set.str[STRING_RTSP_STREAM_URI];
diff --git a/lib/smtp.c b/lib/smtp.c
index 3eb534cd3..dada087a9 100644
--- a/lib/smtp.c
+++ b/lib/smtp.c
@@ -1256,8 +1256,10 @@ static CURLcode smtp_done(struct connectdata *conn, CURLcode status,
 
     /* Run the state-machine
 
-       this should be using the smtp_multi_statemach function but we have no
-       support for non-blocking DONE operations!
+       TODO: when the multi interface is used, this _really_ should be using
+       the smtp_multi_statemach function but we have no general support for
+       non-blocking DONE operations, not in the multi state machine and with
+       Curl_done() invokes on several places in the code!
     */
     result = smtp_block_statemach(conn);
   }
diff --git a/lib/splay.c b/lib/splay.c
index aec353b2d..b87b6cfe2 100644
--- a/lib/splay.c
+++ b/lib/splay.c
@@ -211,7 +211,7 @@ struct Curl_tree *Curl_splaygetbest(struct timeval i,
 /* Deletes the very node we point out from the tree if it's there. Stores a
  * pointer to the new resulting tree in 'newroot'.
  *
- * Returns zero on success and non-zero on errors!
+ * Returns zero on success and non-zero on errors! TODO: document error codes.
  * When returning error, it does not touch the 'newroot' pointer.
  *
  * NOTE: when the last node of the tree is removed, there's no tree left so
diff --git a/lib/ssh.c b/lib/ssh.c
index 2b01e94f5..f9bbdf104 100644
--- a/lib/ssh.c
+++ b/lib/ssh.c
@@ -296,6 +296,10 @@ static CURLcode libssh2_session_error_to_CURLE(int err)
       return CURLE_AGAIN;
   }
 
+  /* TODO: map some more of the libssh2 errors to the more appropriate CURLcode
+     error code, and possibly add a few new SSH-related one. We must however
+     not return or even depend on libssh2 errors in the public libcurl API */
+
   return CURLE_SSH;
 }
 
@@ -2820,8 +2824,10 @@ static CURLcode ssh_connect(struct connectdata *conn, bool *done)
   if(data->set.str[STRING_SSH_KNOWNHOSTS]) {
     int rc;
     ssh->kh = libssh2_knownhost_init(ssh->ssh_session);
-    if(!ssh->kh)
+    if(!ssh->kh) {
+      /* eeek. TODO: free the ssh_session! */
       return CURLE_FAILED_INIT;
+    }
 
     /* read all known hosts from there */
     rc = libssh2_knownhost_readfile(ssh->kh,
@@ -2958,8 +2964,10 @@ static CURLcode ssh_done(struct connectdata *conn, CURLcode status)
   if(!status) {
     /* run the state-machine
 
-       This should be using the ssh_multi_statemach function but we have no
-       support for non-blocking DONE operations!
+       TODO: when the multi interface is used, this _really_ should be using
+       the ssh_multi_statemach function but we have no general support for
+       non-blocking DONE operations, not in the multi state machine and with
+       Curl_done() invokes on several places in the code!
     */
     result = ssh_block_statemach(conn, FALSE);
   }
diff --git a/lib/telnet.c b/lib/telnet.c
index 3975209bd..2086aa396 100644
--- a/lib/telnet.c
+++ b/lib/telnet.c
@@ -1220,6 +1220,7 @@ CURLcode telrcv(struct connectdata *conn,
 }
 
 /* Escape and send a telnet data block */
+/* TODO: write large chunks of data instead of one byte at a time */
 static CURLcode send_telnet_data(struct connectdata *conn,
                                  char *buffer, ssize_t nread)
 {
diff --git a/lib/url.c b/lib/url.c
index 1be4c2805..feb4517fc 100644
--- a/lib/url.c
+++ b/lib/url.c
@@ -6272,6 +6272,8 @@ CURLcode Curl_do(struct connectdata **connp, bool *done)
  * second stage DO state which (wrongly) was introduced to support FTP's
  * second connection.
  *
+ * TODO: A future libcurl should be able to work away this state.
+ *
  * 'complete' can return 0 for incomplete, 1 for done and -1 for go back to
  * DOING state there's more work to do!
  */
diff --git a/lib/vtls/gtls.c b/lib/vtls/gtls.c
index 093cd4e98..1c1cc2f7b 100644
--- a/lib/vtls/gtls.c
+++ b/lib/vtls/gtls.c
@@ -1541,6 +1541,12 @@ static int Curl_gtls_seed(struct SessionHandle *data)
 
   if(!ssl_seeded || data->set.str[STRING_SSL_RANDOM_FILE] ||
      data->set.str[STRING_SSL_EGDSOCKET]) {
+
+    /* TODO: to a good job seeding the RNG
+       This may involve the gcry_control function and these options:
+       GCRYCTL_SET_RANDOM_SEED_FILE
+       GCRYCTL_SET_RNDEGD_SOCKET
+    */
     ssl_seeded = TRUE;
   }
   return 0;
diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c
index 57d945ab9..b2520e83d 100644
--- a/lib/vtls/openssl.c
+++ b/lib/vtls/openssl.c
@@ -2385,6 +2385,11 @@ static CURLcode get_cert_chain(struct connectdata *conn,
         print_pubkey_BN(dh, priv_key, i);
         print_pubkey_BN(dh, pub_key, i);
         break;
+#if 0
+      case EVP_PKEY_EC: /* symbol not present in OpenSSL 0.9.6 */
+        /* left TODO */
+        break;
+#endif
       }
       EVP_PKEY_free(pubkey);
     }
diff --git a/lib/x509asn1.c b/lib/x509asn1.c
index 0cf8ee55b..a3dfd646b 100644
--- a/lib/x509asn1.c
+++ b/lib/x509asn1.c
@@ -857,6 +857,11 @@ static void do_pubkey(struct SessionHandle * data, int certnum,
     do_pubkey_field(data, certnum, "dh(g)", &elem);
     do_pubkey_field(data, certnum, "dh(pub_key)", &pk);
   }
+#if 0 /* Patent-encumbered. */
+  else if(curl_strequal(algo, "ecPublicKey")) {
+    /* Left TODO. */
+  }
+#endif
 }
 
 CURLcode Curl_extract_certinfo(struct connectdata * conn,
diff --git a/src/tool_cb_prg.c b/src/tool_cb_prg.c
index e6ec032ab..9e3c5fb4e 100644
--- a/src/tool_cb_prg.c
+++ b/src/tool_cb_prg.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
  *
  * This software is licensed as described in the file COPYING, which
  * you should have received as part of this distribution. The terms
@@ -117,8 +117,11 @@ void progressbarinit(struct ProgressData *bar,
   if(config->use_resume)
     bar->initial_size = config->resume_from;
 
+/* TODO: get terminal width through ansi escapes or something similar.
+   try to update width when xterm is resized... - 19990617 larsa */
 #ifndef __EMX__
-  /* OS/2 users most likely won't have this env var set, and besides that
+  /* 20000318 mgs
+   * OS/2 users most likely won't have this env var set, and besides that
    * we're using our own way to determine screen width */
   colp = curlx_getenv("COLUMNS");
   if(colp) {
@@ -133,7 +136,8 @@ void progressbarinit(struct ProgressData *bar,
   else
     bar->width = 79;
 #else
-  /* We use this emx library call to get the screen width, and subtract
+  /* 20000318 mgs
+   * We use this emx library call to get the screen width, and subtract
    * one from what we got in order to avoid a problem with the cursor
    * advancing to the next line if we print a string that is as long as
    * the screen is wide. */
diff --git a/src/tool_operate.c b/src/tool_operate.c
index b84b54c39..66ab0fabb 100644
--- a/src/tool_operate.c
+++ b/src/tool_operate.c
@@ -116,6 +116,7 @@ CURLcode curl_easy_perform_ev(CURL *easy);
 static bool is_fatal_error(CURLcode code)
 {
   switch(code) {
+  /* TODO: Should CURLE_SSL_CACERT be included as critical error ? */
   case CURLE_FAILED_INIT:
   case CURLE_OUT_OF_MEMORY:
   case CURLE_UNKNOWN_OPTION:
@@ -855,6 +856,8 @@ static CURLcode operate_do(struct GlobalConfig *global,
 
 #if !defined(CURL_DISABLE_PROXY)
         {
+          /* TODO: Make this a run-time check instead of compile-time one. */
+
           my_setopt_str(curl, CURLOPT_PROXY, config->proxy);
           my_setopt_str(curl, CURLOPT_PROXYUSERPWD, config->proxyuserpwd);
 
@@ -1460,6 +1463,10 @@ static CURLcode operate_do(struct GlobalConfig *global,
                    * file (or terminal). If we write to a file, we must rewind
                    * or close/re-open the file so that the next attempt starts
                    * over from the beginning.
+                   *
+                   * TODO: similar action for the upload case. We might need
+                   * to start over reading from a previous point if we have
+                   * uploaded something when this was returned.
                    */
                   break;
                 }
@@ -1534,6 +1541,8 @@ static CURLcode operate_do(struct GlobalConfig *global,
                download was not successful. */
             long response;
             if(CURLE_OK == result) {
+              /* TODO We want to try next resource when download was
+                 not successful. How to know that? */
               char *effective_url = NULL;
               curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_URL, &effective_url);
               if(effective_url &&
@@ -1715,6 +1724,9 @@ static CURLcode operate_do(struct GlobalConfig *global,
             break;
           mlres = mlres->next;
           if(mlres == NULL)
+            /* TODO If metalink_next_res is 1 and mlres is NULL,
+             * set res to error code
+             */
             break;
         }
         else