Add a bit of documentation (#17)

* Add a bit of documentation

I've met that function! 😊

* Update URLProvider.java

* Provide additional explanation of the function

* Provide additional explanation of the function

* Update index.js

* Update URLProvider.java

* Add function description to python and go as well

* Show maven debug output when building/testing java implementation

Author: owlishDeveloper

.taskcluster.yml

@@ -111,7 +111,7 @@ tasks:
           cd repo
           git config advice.detachedHead false
           git checkout {{event.head.sha}}
-          mvn install
+          mvn -X -e install
     metadata:
       name: taskcluster-lib-urls java test
       description: Run library test suite - java

src/index.js

@@ -175,7 +175,18 @@ module.exports = {
   },
 
   /**
-   * Generate URL for Taskcluser UI.
+   * Generate URL for Taskcluser UI. The purpose of the function is to switch on rootUrl:
+   * "The driver for having a ui method is so we can just call ui with a path and any root url, 
+   *  and the returned url should work for both our current deployment (with root URL = https://taskcluster.net) 
+   *  and any future deployment. The returned value is essentially rootURL == 'https://taskcluster.net' 
+   *  ? 'https://tools.taskcluster.net/${path}' 
+   *  : '${rootURL}/${path}'. "
+   *
+   * @param rootUrl - string. Expected to be without a trailing slash
+   * @param path - string. The rest of the path to append to the rootUrl.
+   * Can start either with a slash or not.
+   *
+   * @returns string. The resulting url
    */
   ui(rootUrl, path) {
     return withRootUrl(rootUrl).ui(path);

src/main/java/org/mozilla/taskcluster/urls/URLProvider.java

@@ -29,7 +29,14 @@ public interface URLProvider {
     public String schema(String service, String schema);
 
     /**
-     * Generate URL for Taskcluser UI.
+     * Generate URL for Taskcluser UI. The purpose of the function is to switch on rootUrl:
+     * "The driver for having a ui method is so we can just call ui with a path and any root url, 
+     *  and the returned url should work for both our current deployment (with root URL = https://taskcluster.net) 
+     *  and any future deployment. The returned value is essentially rootURL == 'https://taskcluster.net' 
+     *  ? 'https://tools.taskcluster.net/${path}' 
+     *  : '${rootURL}/${path}'. "
+     *
+     * @param path - may or may not have an initial slash
      */
     public String ui(String path);
 

taskcluster_urls/__init__.py

@@ -44,7 +44,15 @@ def schema(root_url, service, name):
         return '{}/schemas/{}/{}'.format(root_url, service, name)
 
 def ui(root_url, path):
-    """Generate URL for a path in the Taskcluster ui."""
+    """
+    Generate URL for a path in the Taskcluster ui.
+    The purpose of the function is to switch on rootUrl:
+    "The driver for having a ui method is so we can just call ui with a path and any root url,
+    and the returned url should work for both our current deployment (with root URL = https://taskcluster.net)
+    and any future deployment. The returned value is essentially rootURL == 'https://taskcluster.net'
+    'https://tools.taskcluster.net/${path}'
+    '${rootURL}/${path}' "
+    """
     root_url = root_url.rstrip('/')
     path = path.lstrip('/')
     if root_url == OLD_ROOT_URL:

tcurls.go

@@ -61,6 +61,12 @@ func Schema(rootURL string, service string, name string) string {
 }
 
 // UI generates a url for a page in taskcluster tools site
+// The purpose of the function is to switch on rootUrl:
+// "The driver for having a ui method is so we can just call ui with a path and any root url,
+// and the returned url should work for both our current deployment (with root URL = https://taskcluster.net)
+// and any future deployment. The returned value is essentially rootURL == 'https://taskcluster.net'
+// ? 'https://tools.taskcluster.net/${path}'
+// : '${rootURL}/${path}' "
 func UI(rootURL string, path string) string {
 	path = strings.TrimLeft(path, "/")
 	switch r := strings.TrimRight(rootURL, "/"); r {