[pinpoint] Docstrings for models/change/repository.py.

dashboard/dashboard/pinpoint/models/change/repository.py

Index: dashboard/dashboard/pinpoint/models/change/repository.py
diff --git a/dashboard/dashboard/pinpoint/models/change/repository.py b/dashboard/dashboard/pinpoint/models/change/repository.py
index 52785829d509928fda34e3d67d8e863c7b8e3217..615d39774b921283279bcf7b03e50d45345617ec 100644
--- a/dashboard/dashboard/pinpoint/models/change/repository.py
+++ b/dashboard/dashboard/pinpoint/models/change/repository.py
@@ -10,11 +10,51 @@ _URLS_TO_NAMES_KEY = 'repository_urls_to_names'
 
 
 def RepositoryUrl(name):
+  """Returns the URL of a repository, given its short name.
+
+  If a repository moved locations or has multiple locations, a repository can
+  have multiple URLs. The returned URL should be the most canonical one.

[perezju, 2017/09/25 09:28:43]

nit: "most canonical" -> "current canonical" ? (not entirely sure if it reads
better)

[dtu, 2017/09/25 20:35:10]

Done.

+
+  Args:
+    name: The short name of the repository.
+
+  Returns:
+    A URL string, not including '.git'.
+  """
   repositories = namespaced_stored_object.Get(_REPOSITORIES_KEY)
+  # We have the 'repository_url' key in case we want to add more fields later.
   return repositories[name]['repository_url']
 
 
 def Repository(url, add_if_missing=False):
+  """Returns the short repository name, given its URL.
+
+  By default, the short repository name is the last part of the URL.
+  E.g. "https://chromium.googlesource.com/v8/v8": "v8"
+  In some cases this is ambiguous, so the names can be manually adjusted.
+  E.g. "../chromium/src": "chromium" and "../breakpad/breakpad/src": "breakpad"
+
+  If a repository moved locations or has multiple locations, multiple URLs can
+  map to the same name. This should only be done if they are exact mirrors and
+  have the same git hashes.
+  "https://webrtc.googlesource.com/src": "webrtc"
+  "https://webrtc.googlesource.com/src/webrtc": "old_webrtc"
+  "https://chromium.googlesource.com/external/webrtc/trunk/webrtc": "old_webrtc"
+
+  Internally, all repositories are stored by short name, which always maps to
+  the most canonical URL, so old URLs are automatically "upconverted".

[perezju, 2017/09/25 09:28:43]

ditto

[dtu, 2017/09/25 20:35:09]

Done.

+
+  Args:
+    url: The repository URL.
+    add_if_missing: If True, also attempts to add the URL to the database with
+      the default name mapping. Throws an exception if there's a name collision.
+
+  Returns:
+    The short name as a string.
+
+  Raises:
+    AssertionError: add_if_missing is True and there's a name collision.
+  """
   if url.endswith('.git'):
     url = url[:-4]
 
@@ -28,6 +68,16 @@ def Repository(url, add_if_missing=False):
 
 
 def _AddRepository(url):
+  """Add a repository URL to the database with the default name mapping.
+
+  The default short repository name is the last part of the URL.
+
+  Returns:
+    The short repository name.
+
+  Raises:
+    AssertionError: The default name is already in the database.
+  """
   name = url.split('/')[-1]
 
   # Add to main repositories dict.