2 files changed, 25 insertions, 12 deletions
diff --git a/resources/src/mediawiki.util/jquery.accessKeyLabel.js b/resources/src/mediawiki.util/jquery.accessKeyLabel.js
index 3505b2bfb28f..d3db7061e0ec 100644
--- a/resources/src/mediawiki.util/jquery.accessKeyLabel.js
+++ b/resources/src/mediawiki.util/jquery.accessKeyLabel.js
@@ -1,7 +1,5 @@
 /**
  * jQuery plugin to update the tooltip to show the correct access key
- *
- * @class jQuery.plugin.accessKeyLabel
  */
 
 // Whether to use 'test-' instead of correct prefix (for unit tests)
@@ -174,7 +172,13 @@ function updateTooltip( element ) {
 /**
  * Update the titles for all elements in a jQuery selection.
  *
+ * @class updateTooltipAccessKeys
+ * @memberof jQuery.fn
  * @return {jQuery}
+ * @example
+ *   // Converts tooltip "[z]" to associated browser shortcut key e.g. "[ctrl-option-z]"
+ *   var $a = $('<a href="/wiki/Main_Page" title="Visit the main page [z]" accesskey="z"><span>Main page</span></a>');
+ *   $a.updateTooltipAccessKeys();
  * @chainable
  */
 $.fn.updateTooltipAccessKeys = function () {
@@ -183,12 +187,6 @@ $.fn.updateTooltipAccessKeys = function () {
 	} );
 };
 
-/**
- * getAccessKeyLabel
- *
- * @method updateTooltipAccessKeys_getAccessKeyLabel
- * @inheritdoc #getAccessKeyLabel
- */
 $.fn.updateTooltipAccessKeys.getAccessKeyLabel = getAccessKeyLabel;
 
 /**
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
 		} );