Allow sorting, add some more docs

Author: Seldaek

README.md

@@ -49,6 +49,7 @@ $generator->scanPaths('path/to/scan');
 $generator->scanPaths('path/to/scan2');
 
 $classMap = $generator->getClassMap();
+$classMap->sort(); // optionally sort classes alphabetically
 foreach ($classMap->getMap() as $symbol => $path) {
     // do your thing
 }

src/ClassMap.php

@@ -33,6 +33,8 @@ class ClassMap
     private $psrViolations = [];
 
     /**
+     * Returns the class map, which is a list of paths indexed by class name
+     *
      * @return array<class-string, non-empty-string>
      */
     public function getMap(): array
@@ -41,6 +43,14 @@ public function getMap(): array
     }
 
     /**
+     * Returns warning strings containing details about PSR-0/4 violations that were detected
+     *
+     * Violations are for ex a class which is in the wrong file/directory and thus should not be
+     * found using psr-0/psr-4 autoloading but was found by the ClassMapGenerator as it scans all files.
+     *
+     * This is only happening when scanning paths using psr-0/psr-4 autoload type. Classmap type
+     * always accepts every class as it finds it.
+     *
      * @return string[]
      */
     public function getPsrViolations(): array
@@ -51,6 +61,8 @@ public function getPsrViolations(): array
     /**
      * A map of class names to their list of ambiguous paths
      *
+     * This occurs when the same class can be found in several files
+     *
      * To get the path the class is being mapped to, call getClassPath
      *
      * @return array<class-string, array<non-empty-string>>
@@ -60,6 +72,14 @@ public function getAmbiguousClasses(): array
         return $this->ambiguousClasses;
     }
 
+    /**
+     * Sorts the class map alphabetically by class names
+     */
+    public function sort(): void
+    {
+        ksort($this->map);
+    }
+
     /**
      * @param class-string $className
      * @param non-empty-string $path