Merge "Improve jsdoc for tableOfContents.js and sectionObserver.js"

resources/skins.vector.es6/sectionObserver.js

@@ -3,6 +3,19 @@
  * @param {HTMLElement} element The section that triggered the new intersection change.
  */
 
+/**
+ * @typedef {Object} SectionObserverProps
+ * @property {NodeList} elements A list of HTML elements to observe for
+ * intersection changes. This list can be updated through the `elements` setter.
+ * @property {OnIntersection} onIntersection Called when a new intersection is observed.
+ * @property {number} [topMargin] The number of pixels to shrink the top of
+ * the viewport's bounding box before calculating intersections. This is useful
+ * for sticky elements (e.g. sticky headers). Defaults to 0 pixels.
+ * @property {number} [throttleMs] The number of milliseconds that the scroll
+ * handler should be throttled.
+ */
+
+// eslint-disable-next-line jsdoc/require-returns
 /**
  * Observe intersection changes with the viewport for one or more elements. This
  * is intended to be used with the headings in the content so that the
@@ -20,16 +33,8 @@
  * observed tags off the main thread and in a manner that does not cause
  * expensive forced synchronous layouts.
  *
- * @param {Object} props
- * @param {NodeList} props.elements A list of HTML elements to observe for
- * intersection changes. This list can be updated through the `elements` setter.
- * @param {OnIntersection} props.onIntersection Called when a new intersection is observed.
- * @param {number} [props.topMargin] The number of pixels to shrink the top of
- * the viewport's bounding box before calculating intersections. This is useful
- * for sticky elements (e.g. sticky headers). Defaults to 0 pixels.
- * @param {number} [props.throttleMs] The number of milliseconds that the scroll
- * handler should be throttled.
- * @return {SectionObserver}
+ * @namespace SectionObserver
+ * @param {SectionObserverProps} props
  */
 module.exports = function sectionObserver( props ) {
 	props = Object.assign( {
@@ -123,6 +128,9 @@ module.exports = function sectionObserver( props ) {
 
 	/**
 	 * Pauses intersection observation until `resume` is called.
+	 *
+	 * @memberof SectionObserver
+	 * @instance
 	 */
 	function pause() {
 		unbindScrollListener();
@@ -132,6 +140,9 @@ module.exports = function sectionObserver( props ) {
 
 	/**
 	 * Resumes intersection observation.
+	 *
+	 * @memberof SectionObserver
+	 * @instance
 	 */
 	function resume() {
 		bindScrollListener();
@@ -140,6 +151,9 @@ module.exports = function sectionObserver( props ) {
 	/**
 	 * Cleans up event listeners and intersection observer. Should be called when
 	 * the observer is permanently no longer needed.
+	 *
+	 * @memberof SectionObserver
+	 * @instance
 	 */
 	function unmount() {
 		unbindScrollListener();
@@ -150,6 +164,8 @@ module.exports = function sectionObserver( props ) {
 	 * Set a list of HTML elements to observe for intersection changes.
 	 *
 	 * @param {NodeList} list
+	 * @memberof SectionObserver
+	 * @instance
 	 */
 	function setElements( list ) {
 		props.elements = list;
@@ -159,13 +175,6 @@ module.exports = function sectionObserver( props ) {
 	// Calculate intersection on page load.
 	calcIntersection();
 
-	/**
-	 * @typedef {Object} SectionObserver
-	 * @property {pause} pause
-	 * @property {resume} resume
-	 * @property {unmount} unmount
-	 * @property {setElements} setElements
-	 */
 	return {
 		pause,
 		resume,

resources/skins.vector.es6/tableOfContents.js

@@ -22,11 +22,12 @@ const TOGGLE_CLASS = 'sidebar-toc-toggle';
  * @property {onToggleClick} onToggleClick Called when a list item is clicked.
  */
 
+// eslint-disable-next-line jsdoc/require-returns
 /**
  * Initializes the sidebar's Table of Contents.
  *
+ * @namespace TableOfContents
  * @param {TableOfContentsProps} props
- * @return {TableOfContents}
  */
 module.exports = function tableOfContents( props ) {
 	let /** @type {HTMLElement | undefined} */ activeTopSection;
@@ -107,6 +108,8 @@ module.exports = function tableOfContents( props ) {
 	 * to a top level heading in the ToC.
 	 *
 	 * @param {string} id
+	 * @memberof TableOfContents
+	 * @instance
 	 */
 	function expandSection( id ) {
 		const tocSection = document.getElementById( id );
@@ -133,8 +136,9 @@ module.exports = function tableOfContents( props ) {
 	}
 
 	/**
-	 *
 	 * @param {string} id
+	 * @memberof TableOfContents
+	 * @instance
 	 */
 	function changeActiveSection( id ) {
 
@@ -176,6 +180,8 @@ module.exports = function tableOfContents( props ) {
 
 	/**
 	 * @param {string} id
+	 * @memberof TableOfContents
+	 * @instance
 	 */
 	function toggleExpandSection( id ) {
 		const expandedSectionIds = getExpandedSectionIds();
@@ -227,16 +233,6 @@ module.exports = function tableOfContents( props ) {
 
 	initialize();
 
-	/**
-	 * @typedef {Object} TableOfContents
-	 * @property {changeActiveSection} changeActiveSection
-	 * @property {expandSection} expandSection
-	 * @property {toggleExpandSection} toggleExpandSection
-	 * @property {string} ACTIVE_SECTION_CLASS
-	 * @property {string} EXPANDED_SECTION_CLASS
-	 * @property {string} LINK_CLASS
-	 * @property {string} TOGGLE_CLASS
-	 */
 	return {
 		expandSection,
 		changeActiveSection,