mediawiki.user: Clarify sessionId documentation

The existing documentation creates the impression that this ID
remains the same until the browser session ends (like a session
cookie), which has led to misunderstandings about the results of
past data analyses.

See T118063#4547178 ff.

Change-Id: Ia2e156088b9e903836ceb8e2f9e77f9fb46a49fe

diff --git a/resources/src/mediawiki.user.js b/resources/src/mediawiki.user.js
index aada50c..5f629e7 100644 (file)
--- a/resources/src/mediawiki.user.js
+++ b/resources/src/mediawiki.user.js
@@ -136,10 +136,21 @@
                },
 
                /**
-                * Get an automatically generated random ID (persisted in sessionStorage)
+                * Retrieve a random ID persisted in sessionStorage, generating it if needed
                 *
-                * This ID is ephemeral for everyone, staying in their browser only until they
-                * close their browsing session.
+                * This ID is stored in sessionStorage and persists within a single tab,
+                * including between page views through links and form submissions,
+                * and when going forwards/backwards in browser history, and when restoring
+                * a closed tab, or restoring a closed browser session.
+                *
+                * This is different from session cookies, because it is not shared between
+                * tabs of the same browser. Two simultaneous pageviews in the same browser
+                * can have different session IDs. The ID is also not re-used when opening
+                * a new tab to a website after fully closing others.
+                *
+                * See https://phabricator.wikimedia.org/T118063#4547178 and
+                * https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage
+                * for more information.
                 *
                 * @return {string} Random session ID
                 */