Added comments and reqordings based on code review

pip/wheel.py

@@ -131,6 +131,11 @@ def move_wheel_files(name, req, wheeldir, user=False, home=None, root=None):
     info_dir = []
     data_dirs = []
     source = wheeldir.rstrip(os.path.sep) + os.path.sep
+
+    # Record details of the files moved
+    #   installed = files copied from the wheel to the destination
+    #   changed = files changed while installing (scripts #! line typically)
+    #   generated = files newly generated during the install (script wrappers)
     installed = {}
     changed = set()
     generated = []
@@ -215,6 +220,24 @@ def move_wheel_files(name, req, wheeldir, user=False, home=None, root=None):
     maker.variants = set(('', ))
 
     # Special case pip and setuptools to generate versioned wrappers
+    #
+    # The issue is that some projects (specifically, pip and setuptools) use
+    # code in setup.py to create "versioned" entry points - pip2.7 on Python
+    # 2.7, pip3.3 on Python 3.3, etc. But these entry points are baked into
+    # the wheel metadata at build time, and so if the wheel is installed with
+    # a *different* version of Python the entry points will be wrong. The
+    # correct fix for this is to enhance the metadata to be able to describe
+    # such versioned entry points, but that won't happen till Metadata 2.0 is
+    # available.
+    # In the meantime, projects using versioned entry points will either have
+    # incorrect versioned entry points, or they will not be able to distribute
+    # "universal" wheels (i.e., they will need a wheel per Python version).
+    #
+    # Because setuptools and pip are bundled with _ensurepip and virtualenv,
+    # we need to use universal wheels. So, as a stopgap until Metadata 2.0, we
+    # override the versioned entry points in the wheel and generate the
+    # correct ones. This code is purely a short-term measure until Metadat 2.0
+    # is available.
     pip_script = console.pop('pip', None)
     if pip_script:
         spec = 'pip = ' + pip_script
@@ -239,6 +262,7 @@ def move_wheel_files(name, req, wheeldir, user=False, home=None, root=None):
         for k in easy_install_ep:
             del console[k]
 
+    # Generate the console and GUI entry points specified in the wheel
     if len(console) > 0:
         generated.extend(maker.make_multiple(['%s = %s' % kv for kv in console.items()]))
     if len(gui) > 0:

tests/functional/test_install_wheel.py

@@ -133,7 +133,8 @@ def test_install_from_wheel_with_legacy(script, data):
 
 def test_install_from_wheel_no_setuptools_entrypoint(script, data):
     """
-    Test installing scripts (setuptools entrypoints are omitted)
+    Test that when we generate scripts, any existing setuptools wrappers in
+    the wheel are skipped.
     """
     result = script.pip('install', 'script.wheel1==0.1', '--use-wheel',
                      '--no-index', '--find-links='+data.find_links,
@@ -144,6 +145,11 @@ def test_install_from_wheel_no_setuptools_entrypoint(script, data):
         wrapper_file = script.bin / 't1'
     wrapper_helper = script.bin / 't1-script.py'
 
+    # The wheel has t1.exe and t1-script.py. We will be generating t1 or
+    # t1.exe depending on the platform. So we check that the correct wrapper
+    # is present and that the -script.py helper has been skipped. We can't
+    # easily test that the wrapper from the wheel has been skipped /
+    # overwritten without getting very platform-dependent, so omit that.
     assert wrapper_file in result.files_created
     assert wrapper_helper not in result.files_created