From 8eab05da93fce949811616644a7301802eafa963 Mon Sep 17 00:00:00 2001
From: Kasper Nilsson <kaspern@google.com>
Date: Mon, 24 Jul 2017 15:39:21 -0700
Subject: [PATCH] Document upgradeUrl functionality

Bug: Issue 6708
Change-Id: I061a410246771948277b752b47eb8b821fd5e02d
---
 .../app/elements/core/gr-navigation/gr-navigation.html     | 7 ++++++-
 polygerrit-ui/app/elements/core/gr-router/gr-router.js     | 7 +++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/polygerrit-ui/app/elements/core/gr-navigation/gr-navigation.html b/polygerrit-ui/app/elements/core/gr-navigation/gr-navigation.html
index d6e2e2fabd..713d7718f6 100644
--- a/polygerrit-ui/app/elements/core/gr-navigation/gr-navigation.html
+++ b/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) {
diff --git a/polygerrit-ui/app/elements/core/gr-router/gr-router.js b/polygerrit-ui/app/elements/core/gr-router/gr-router.js
index 566dd5dedd..d1d717bcd2 100644
--- a/polygerrit-ui/app/elements/core/gr-router/gr-router.js
+++ b/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) {