Bug 553970 - Fix nsIURL::GetRelativeSpec documentation. r=biesi

--HG--
extra : rebase_source : 874de0e571120e2b9034d924b4e4f33f808bc0f0

netwerk/base/public/nsIURL.idl

@@ -169,10 +169,18 @@ interface nsIURL : nsIURI
     AUTF8String getCommonBaseSpec(in nsIURI aURIToCompare);
 
     /**
-     * This method takes a uri and returns a substring of this if it can be
-     * made relative to the uri passed in.  If no commonality is found, the
-     * entire uri spec is returned.  If they are identical, "" is returned.
-     * Filename, query, etc are always returned except when uris are identical.
+     * This method tries to create a string which specifies the location of the
+     * argument relative to |this|.  If the argument and |this| are equal, the
+     * method returns "".  If any of the URIs' scheme, host, userpass, or port
+     * don't match, the method returns the full spec of the argument.
+     *
+     * Examples:
+     *    this.spec               aURIToCompare.spec        result
+     * 1) http://mozilla.org/     http://www.mozilla.org/   http://www.mozilla.org/
+     * 2) http://mozilla.org/     http://www.mozilla.org    http://www.mozilla.org/
+     * 3) http://foo.com/bar/     http://foo.com:80/bar/    ""
+     * 4) http://foo.com/         http://foo.com/a.htm#b    a.html#b
+     * 5) http://foo.com/a/b/     http://foo.com/c          ../../c
      */
     AUTF8String getRelativeSpec(in nsIURI aURIToCompare);
 

netwerk/test/unit/test_bug553970.js

@@ -0,0 +1,28 @@
+const Cc = Components.classes;
+
+function makeURL(spec) {
+  return Cc["@mozilla.org/network/io-service;1"].
+           getService(Components.interfaces.nsIIOService).
+           newURI(spec, null, null).
+           QueryInterface(Components.interfaces.nsIURL);
+}
+
+// Checks that nsIURL::GetRelativeSpec does what it claims to do.
+function run_test() {
+
+  // Elements of tests have the form [this.spec, aURIToCompare.spec, expectedResult].
+  let tests = [
+    ["http://mozilla.org/",  "http://www.mozilla.org/", "http://www.mozilla.org/"],
+    ["http://mozilla.org/",  "http://www.mozilla.org",  "http://www.mozilla.org/"],
+    ["http://foo.com/bar/",  "http://foo.com:80/bar/",  ""                       ],
+    ["http://foo.com/",      "http://foo.com/a.htm#b",  "a.htm#b"                ],
+    ["http://foo.com/a/b/",  "http://foo.com/c",        "../../c"                ],
+  ];
+
+  for (var i = 0; i < tests.length; i++) {
+    let url1 = makeURL(tests[i][0]);
+    let url2 = makeURL(tests[i][1]);
+    let expected = tests[i][2];
+    do_check_eq(expected, url1.getRelativeSpec(url2));
+  }
+}