Add jsdoc with jsdoc-wmf-theme

jsduck is preventing us from using ES6 syntax and has not
been supported for some time. It is also difficult to setup
locally due its use of Ruby.

Introduce jsdoc and remove jsduck per T138401#9335987
Link to static copy of jsduck explaining the state

This does the bare minimum - the docs are built to the folder
docs/js/index.html and only one module is ported over to allow
us to provide feedback on the end result.

Bug: T138401
Change-Id: I1a351ac5aec731bb79a877023ac10988ec3ec786

1 files changed, 19 insertions, 4 deletions

diff --git a/resources/src/mediawiki.util/util.js b/resources/src/mediawiki.util/util.js
index f0dc6834f92f..9255503b274f 100644
--- a/resources/src/mediawiki.util/util.js
+++ b/resources/src/mediawiki.util/util.js
@@ -49,8 +49,7 @@ function escapeIdInternal( str, mode ) {
 /**
  * Utility library provided by the `mediawiki.util` module.
  *
- * @class mw.util
- * @singleton
+ * @exports mw.util
  */
 var util = {
 
@@ -503,6 +502,7 @@ var util = {
 	 * @param {string} [label] of the new portlet.
 	 * @param {string} [before] selector of the element preceding the new portlet. If not passed
 	 *  the caller is responsible for appending the element to the DOM before using addPortletLink.
+	 * @fires util_addPortlet
 	 * @return {HTMLElement|null} will be null if it was not possible to create an portlet with
 	 *  the required information e.g. the selector given in before parameter could not be resolved
 	 *  to an existing element in the page.
@@ -540,12 +540,15 @@ var util = {
 			}
 		}
 		/**
-		 * @event util.addPortlet
-		 *
 		 * Fires when a portlet is successfully created.
 		 *
+		 * @event util_addPortlet
 		 * @param {HTMLElement} portlet the portlet that was created.
 		 * @param {string|null} before the css selector used to append to the DOM.
+		 * @example
+		 *   mw.hook( 'util.addPortlet' ).add( ( p ) => {
+		 *    p.style.border = 'solid 1px black';
+		 *   } );
 		 */
 		mw.hook( 'util.addPortlet' ).fire( portlet, before );
 		return portlet;
@@ -698,6 +701,18 @@ var util = {
 			$( link ).updateTooltipAccessKeys();
 		}
 
+		/**
+		 * Fires when a portlet link is successfully created.
+		 *
+		 * @event util_addPortletLink
+		 * @param {HTMLElement} item the portlet link that was created.
+		 * @param {Object} information about the item include id.
+		 * @example
+		 *   mw.hook( 'util.addPortletLink' ).add( ( link ) => {
+		 *    const span = $( '<span class="icon">' );
+		 *    link.appendChild( span );
+		 *   } );
+		 */
 		mw.hook( 'util.addPortletLink' ).fire( item, {
 			id: id
 		} );