pkg_resources.Environment.__getitem__() code cleanup

Better commented the code, especially the result caching & lazy distribution
list sorting strategies implemented there. Added several TODO comments
indicating things to look into there in the future.

General code cleanup:
 - stopped reusing the project_name variable for different purposes
 - added an assertion to detect corrupt distribution list caches

--HG--
extra : source : 86ef8f59ef4e1fc253c155b9ca0856497455372d
Bumped to 3.5.1 in preparation for next release.
Added tag 3.5.1 for changeset 254d8c625f46
Bumped to 3.5.2 in preparation for next release.
Sort _distmap entries on insert. Obviates need for a cache.
Correct sort order by using list.sort with support for 'key' and 'reverse'. This method is less efficient, but allows the tests to pass.
Remove _sort_dists (unused)
Merge pkg_resources.Environment.__getitem__() code cleanup (pull request #47 and subsequent changes).