[PATCH 01 of 11] sslutil: document and slightly refactor sslkwargs

[Gregory Szorc]

# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1462433471 25200
#      Thu May 05 00:31:11 2016 -0700
# Node ID 03b9752157bd4098b2fd9d7b35c969b5c7dc22c6
# Parent  906a1c8a75fd8a18e43e8545eedcbe5222f84647
sslutil: document and slightly refactor sslkwargs

This will help me and any reviewers keep sane as this code
is refactored.

diff --git a/mercurial/sslutil.py b/mercurial/sslutil.py
--- a/mercurial/sslutil.py
+++ b/mercurial/sslutil.py
@@ -227,32 +227,45 @@ def _defaultcacerts():
         dummycert = os.path.join(os.path.dirname(__file__), 'dummycert.pem')
         if os.path.exists(dummycert):
             return dummycert
     if _canloaddefaultcerts:
         return None
     return '!'
 
 def sslkwargs(ui, host):
+    """Determine arguments to pass to wrapsocket().
+
+    ``host`` is the hostname being connected to.
+    """
     kws = {'ui': ui}
+
+    # If a host key fingerprint is on file, it is the only thing that matters
+    # and CA certs don't come into play.
     hostfingerprint = ui.config('hostfingerprints', host)
     if hostfingerprint:
         return kws
+
+    # dispatch sets web.cacerts=! when --insecure is used.
     cacerts = ui.config('web', 'cacerts')
     if cacerts == '!':
-        pass
-    elif cacerts:
+        return kws
+
+    if cacerts:
         cacerts = util.expandpath(cacerts)
         if not os.path.exists(cacerts):
             raise error.Abort(_('could not find web.cacerts: %s') % cacerts)
     else:
+        # CA certs aren't explicitly listed in the config. See if we can load
+        # defaults.
         cacerts = _defaultcacerts()
         if cacerts and cacerts != '!':
             ui.debug('using %s to enable OS X system CA\n' % cacerts)
         ui.setconfig('web', 'cacerts', cacerts, 'defaultcacerts')
+
     if cacerts != '!':
         kws.update({'ca_certs': cacerts,
                     'cert_reqs': ssl.CERT_REQUIRED,
                     })
     return kws
 
 class validator(object):
     def __init__(self, ui, host):