From 922475be6b1c64d3c1a6bdf2bd0a921e120ed5a8 Mon Sep 17 00:00:00 2001
From: Jon Robson <jdlrobson@gmail.com>
Date: Tue, 3 Oct 2023 17:32:27 -0700
Subject: [PATCH] Define stable  and internal APIs

Bug: T348081
Change-Id: I2ca9f27802e5ff1e0738300e2595ea419d49a431
---
 resources/skins.vector.js/AB.js                         | 6 ++++++
 resources/skins.vector.js/scrollObserver.js             | 6 ++++++
 resources/skins.vector.js/setupIntersectionObservers.js | 4 ++++
 3 files changed, 16 insertions(+)

diff --git a/resources/skins.vector.js/AB.js b/resources/skins.vector.js/AB.js
index 96ba565e8..ade2b6459 100644
--- a/resources/skins.vector.js/AB.js
+++ b/resources/skins.vector.js/AB.js
@@ -184,6 +184,12 @@ module.exports = function webABTest( props, token, forceInit ) {
 		// Send data to WikimediaEvents to log A/B test initialization if the subject
 		// has been sampled into the experiment.
 		if ( isInSample() ) {
+			/**
+			 * @event mediawiki.web_AB_test_enrollment
+			 * @internal for use by WikimediaEvents only.
+			 * @property {string} context
+			 * @property {string} action
+			 */
 			mw.hook( WEB_AB_TEST_ENROLLMENT_HOOK ).fire( {
 				group: getBucket(),
 				experimentName: props.name
diff --git a/resources/skins.vector.js/scrollObserver.js b/resources/skins.vector.js/scrollObserver.js
index 0729b6c7f..21bc64077 100644
--- a/resources/skins.vector.js/scrollObserver.js
+++ b/resources/skins.vector.js/scrollObserver.js
@@ -10,6 +10,12 @@ const
  * @param {string} direction the scroll direction
  */
 function firePageTitleScrollHook( direction ) {
+	/**
+	 * @event vector.page_title_scroll
+	 * @internal for use by WikimediaEvents only.
+	 * @property {string} context
+	 * @property {string} action
+	 */
 	if ( direction === 'down' ) {
 		mw.hook( SCROLL_TITLE_HOOK ).fire( {
 			context: SCROLL_TITLE_CONTEXT_BELOW
diff --git a/resources/skins.vector.js/setupIntersectionObservers.js b/resources/skins.vector.js/setupIntersectionObservers.js
index 0dfcfb14a..43423e1e8 100644
--- a/resources/skins.vector.js/setupIntersectionObservers.js
+++ b/resources/skins.vector.js/setupIntersectionObservers.js
@@ -223,6 +223,10 @@ const setupTableOfContents = ( tocElement, bodyContent, initSectionObserverFn )
 	} );
 	mw.hook( 'wikipage.tableOfContents' ).add( function ( sections ) {
 		tableOfContents.reloadTableOfContents( sections ).then( function () {
+			/**
+			 * @stable for use in gadgets and extensions
+			 * @since 1.40
+			 */
 			mw.hook( 'wikipage.tableOfContents.vector' ).fire( sections );
 			updateElements();
 		} );