Add some function documentation and update some existing comments

Reviewed-by: NKurt Roeckx <kurt@openssl.org>
Reviewed-by: NRich Salz <rsalz@openssl.org>

ssl/statem/statem_lib.c

@@ -152,6 +152,16 @@ static void ssl3_take_mac(SSL *s)
 }
 #endif
 
+/*
+ * Comparison function used in a call to qsort (see tls_collect_extensions()
+ * below.)
+ * The two arguments |p1| and |p2| are expected to be pointers to RAW_EXTENSIONs
+ *
+ * Returns:
+ *  1 if the type for p1 is greater than p2
+ *  0 if the type for p1 and p2 are the same
+ * -1 if the type for p1 is less than p2
+ */
 static int compare_extensions(const void *p1, const void *p2)
 {
     const RAW_EXTENSION *e1 = (const RAW_EXTENSION *)p1;
@@ -208,7 +218,7 @@ int tls_collect_extensions(PACKET *packet, RAW_EXTENSION **res,
             goto err;
         }
 
-        /* Second pass: gather the extension types. */
+        /* Second pass: collect the extensions. */
         for (i = 0; i < num_extensions; i++) {
             if (!PACKET_get_net_2(packet, &raw_extensions[i].type) ||
                 !PACKET_get_length_prefixed_2(packet,

ssl/t1_lib.c

@@ -1753,14 +1753,15 @@ static void ssl_check_for_safari(SSL *s, CLIENTHELLO_MSG *hello)
 #endif                          /* !OPENSSL_NO_EC */
 
 /*
- * Parse ClientHello extensions and stash extension info in various parts of
- * the SSL object. Verify that there are no duplicate extensions.
+ * Loop through all remaining ClientHello extensions that we collected earlier
+ * and haven't already processed. For each one parse it and update the SSL
+ * object as required.
  *
  * Behaviour upon resumption is extension-specific. If the extension has no
  * effect during resumption, it is parsed (to verify its format) but otherwise
  * ignored.
  *
- * Consumes the entire packet in |pkt|. Returns 1 on success and 0 on failure.
+ * Returns 1 on success and 0 on failure.
  * Upon failure, sets |al| to the appropriate alert.
  */
 static int ssl_scan_clienthello_tlsext(SSL *s, CLIENTHELLO_MSG *hello, int *al)
@@ -2781,6 +2782,16 @@ int ssl_parse_serverhello_tlsext(SSL *s, PACKET *pkt)
     return 1;
 }
 
+/*
+ * Given a list of extensions that we collected earlier, find one of a given
+ * type and return it.
+ *
+ * |exts| is the set of extensions previously collected.
+ * |numexts| is the number of extensions that we have.
+ * |type| the type of the extension that we are looking for.
+ *
+ * Returns a pointer to the found RAW_EXTENSION data, or NULL if not found.
+ */
 static RAW_EXTENSION *get_extension_by_type(RAW_EXTENSION *exts, size_t numexts,
                                             unsigned int type)
 {