Document upgradeUrl functionality

Bug: Issue 6708
Change-Id: I061a410246771948277b752b47eb8b821fd5e02d

polygerrit-ui/app/elements/core/gr-navigation/gr-navigation.html

@@ -72,7 +72,12 @@ limitations under the License.
       /** @type {Function} */
       _generateUrl: uninitialized,
 
-      /** @type {Function} */
+      /**
+       * Handler for when a legacy URL can be upgraded. Router implementations
+       * may implement as a no-op if route upgrades are not needed.
+       *
+       * @type {Function}
+       */
       _upgradeUrl: uninitialized,
 
       _checkPatchRange(patchNum, basePatchNum) {

polygerrit-ui/app/elements/core/gr-router/gr-router.js

@@ -46,6 +46,13 @@
       page.base(base);
     }
 
+    /**
+     * While resolving Issue 6708, the need for some way to upgrade obsolete
+     * URLs in-place without page reloads became evident.
+     *
+     * This function aims to update the app params and the URL when the URL is
+     * found to be obsolete.
+     */
     const upgradeUrl = params => {
       const url = generateUrl(params);
       if (url !== window.location.pathname) {