fixes and more details (Floris feedback)

pep-0376.txt

@@ -166,6 +166,8 @@ Back to our `zlib` example, we will have::
         MANIFEST
         RECORD
 
+XXX See if we want to keep the 2.5.2-py2.6 part
+
 New functions in pkgutil
 ========================
 
@@ -174,11 +176,15 @@ APIs. The best place to put these APIs seems to be `pkgutil`.
 
 The new functions added in the package are :
 
-- get_egg_info(pkg_name) -> directory or None
+- get_egg_info(pkg_name) -> path or None
 
-  Scans all site-packages directories and look for all `pkg_name*.egg-info` 
-  directory. If founded, returns the path. If the directory is not found, 
-  returns None.
+  Scans all site-packages directories and look for all `pkg_name.egg-info` 
+  directory. Returns the directory path that contains a PKG-INFO that matches
+  `pkg_name` for the `name` metadata. Notice that there should be at most 
+  one result. If moe that one path matches the pkg_name, a DistutilsError
+  is raised.
+
+  If the directory is not found, returns None.
 
 - get_metadata(pkg_name) -> DistributionMetadata or None
 
@@ -202,7 +208,7 @@ Let's use it over our `zlib` example::
     >>> metadata.version
     '2.5.2'
     >>> from distutils.dist import EGG_INFO_FILES
-    >>> get_metadata('zlib', EGG_INFO_FILES.manifest).read()
+    >>> get_egg_info_file('zlib', EGG_INFO_FILES.manifest).read()
     some
     ...
     files