Improved comments for the recent optimization in owners.py

The final improvement of the patch, better comments, was never
included in the CL that got checked in. Here they are.

Bug: 920591
Change-Id: I2a5f7f67d4bbc5b40fdb0e7021795cd204d6f0c8
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/tools/depot_tools/+/1583772
Auto-Submit: Daniel Bratell <bratell@opera.com>
Reviewed-by: Dirk Pranke <dpranke@chromium.org>
Commit-Queue: Daniel Bratell <bratell@opera.com>

owners.py

@@ -125,9 +125,8 @@ class Database(object):
     # Mapping of owners to the paths or globs they own.
     self._owners_to_paths = {EVERYONE: set()}
 
-    # Mappings of paths to authorized owners, via the longest path with no
+    # Mappings of directories -> globs in the directory -> owners
-    # glob in it.
+    # Example: "chrome/browser" -> "chrome/browser/*.h" -> ("john", "maria")
-    # For instance "chrome/browser" -> "chrome/browser/*.h" -> ("john", "maria")
     self._paths_to_owners = {}
 
     # Mapping reviewers to the preceding comment per file in the OWNERS files.
@@ -137,9 +136,13 @@ class Database(object):
     self._fnmatch_cache = {}
 
     # Sets of paths that stop us from looking above them for owners.
-    # (This is implicitly true for the root directory). They are organized
+    # (This is implicitly true for the root directory).
-    # by glob free path so that a 'ui/events/devices/mojo/*_struct_traits*.*'
+    #
-    # rule would be found in 'ui/events/devices/mojo'.
+    # The implementation is a mapping:
+    # Directory -> globs in the directory,
+    #
+    # Example:
+    # 'ui/events/devices/mojo' -> 'ui/events/devices/mojo/*_struct_traits*.*'
     self._stop_looking = {'': set([''])}
 
     # Set of files which have already been read.