Issue #2531688 by kekkis, nod_, eiriksm, evilfurryone: JSDoc toolbar module

6 files changed, 38 insertions, 7 deletions

diff --git a/core/modules/toolbar/js/escapeAdmin.js b/core/modules/toolbar/js/escapeAdmin.js
index f47b8b9..26b8a26 100644
--- a/core/modules/toolbar/js/escapeAdmin.js
+++ b/core/modules/toolbar/js/escapeAdmin.js
@@ -11,10 +11,10 @@
   var escapeAdminPath = sessionStorage.getItem('escapeAdminPath');
   var windowLocation = window.location;
 
-  // Saves the last non-administrative page in the browser to be able to link back
-  // to it when browsing administrative pages. If there is a destination parameter
-  // there is not need to save the current path because the page is loaded within
-  // an existing "workflow".
+  // Saves the last non-administrative page in the browser to be able to link
+  // back to it when browsing administrative pages. If there is a destination
+  // parameter there is not need to save the current path because the page is
+  // loaded within an existing "workflow".
   if (!pathInfo.currentPathIsAdmin && !/destination=/.test(windowLocation.search)) {
     sessionStorage.setItem('escapeAdminPath', windowLocation);
   }
@@ -22,10 +22,13 @@
   /**
    * Replaces the "Home" link with "Back to site" link.
    *
-   * Back to site link points to the last non-administrative page the user visited
-   * within the same browser tab.
+   * Back to site link points to the last non-administrative page the user
+   * visited within the same browser tab.
    *
    * @type {Drupal~behavior}
+   *
+   * @prop {Drupal~behaviorAttach} attach
+   *   Attaches the replacement functionality to the toolbar-escape-admin element.
    */
   Drupal.behaviors.escapeAdmin = {
     attach: function () {
diff --git a/core/modules/toolbar/js/models/ToolbarModel.js b/core/modules/toolbar/js/models/ToolbarModel.js
index 0ddabfa..357692c 100644
--- a/core/modules/toolbar/js/models/ToolbarModel.js
+++ b/core/modules/toolbar/js/models/ToolbarModel.js
@@ -138,9 +138,12 @@
      * @inheritdoc
      *
      * @param {object} attributes
+     *   Attributes for the toolbar.
      * @param {object} options
+     *   Options for the toolbar.
      *
-     * @return {string}
+     * @return {string|undefined}
+     *   Returns an error message if validation failed.
      */
     validate: function (attributes, options) {
       // Prevent the orientation being set to horizontal if it is locked, unless
diff --git a/core/modules/toolbar/js/toolbar.js b/core/modules/toolbar/js/toolbar.js
index e45021d..9a19205 100644
--- a/core/modules/toolbar/js/toolbar.js
+++ b/core/modules/toolbar/js/toolbar.js
@@ -35,6 +35,9 @@
    * Modules register tabs with hook_toolbar().
    *
    * @type {Drupal~behavior}
+   *
+   * @prop {Drupal~behaviorAttach} attach
+   *   Attaches the toolbar rendering functionality to the toolbar element.
    */
   Drupal.behaviors.toolbar = {
     attach: function (context) {
@@ -181,8 +184,11 @@
      * Respond to configured narrow media query changes.
      *
      * @param {Drupal.toolbar.ToolbarModel} model
+     *   A toolbar model
      * @param {string} label
+     *   Media query label.
      * @param {object} mql
+     *   A MediaQueryList object.
      */
     mediaQueryChangeHandler: function (model, label, mql) {
       switch (label) {
@@ -238,8 +244,11 @@
    * Ajax command to set the toolbar subtrees.
    *
    * @param {Drupal.Ajax} ajax
+   *   {@link Drupal.Ajax} object created by {@link Drupal.ajax}.
    * @param {object} response
+   *   JSON response from the Ajax request.
    * @param {number} [status]
+   *   XMLHttpRequest status.
    */
   Drupal.AjaxCommands.prototype.setToolbarSubtrees = function (ajax, response, status) {
     Drupal.toolbar.setSubtrees.resolve(response.subtrees);
diff --git a/core/modules/toolbar/js/toolbar.menu.js b/core/modules/toolbar/js/toolbar.menu.js
index 990c56a..f3c2301 100644
--- a/core/modules/toolbar/js/toolbar.menu.js
+++ b/core/modules/toolbar/js/toolbar.menu.js
@@ -179,9 +179,13 @@
    * A toggle is an interactive element often bound to a click handler.
    *
    * @param {object} options
+   *   Options for the button.
    * @param {string} options.class
+   *   Class to set on the button.
    * @param {string} options.action
+   *   Action for the button.
    * @param {string} options.text
+   *   Used as label for the button.
    *
    * @return {string}
    *   A string representing a DOM fragment.
diff --git a/core/modules/toolbar/js/views/ToolbarAuralView.js b/core/modules/toolbar/js/views/ToolbarAuralView.js
index b6cac03..00f5aa5 100644
--- a/core/modules/toolbar/js/views/ToolbarAuralView.js
+++ b/core/modules/toolbar/js/views/ToolbarAuralView.js
@@ -17,7 +17,9 @@
      * @augments Backbone.View
      *
      * @param {object} options
+     *   Options for the view.
      * @param {object} options.strings
+     *   Various strings to use in the view.
      */
     initialize: function (options) {
       this.strings = options.strings;
@@ -30,6 +32,7 @@
      * Announces an orientation change.
      *
      * @param {Drupal.toolbar.ToolbarModel} model
+     *   The toolbar model in question.
      * @param {string} orientation
      *   The new value of the orientation attribute in the model.
      */
@@ -43,6 +46,7 @@
      * Announces a changed active tray.
      *
      * @param {Drupal.toolbar.ToolbarModel} model
+     *   The toolbar model in question.
      * @param {HTMLElement} tray
      *   The new value of the tray attribute in the model.
      */
diff --git a/core/modules/toolbar/js/views/ToolbarVisualView.js b/core/modules/toolbar/js/views/ToolbarVisualView.js
index a63e2a2..be7ab06 100644
--- a/core/modules/toolbar/js/views/ToolbarVisualView.js
+++ b/core/modules/toolbar/js/views/ToolbarVisualView.js
@@ -10,7 +10,10 @@
   Drupal.toolbar.ToolbarVisualView = Backbone.View.extend(/** @lends Drupal.toolbar.ToolbarVisualView# */{
 
     /**
+     * Event map for the `ToolbarVisualView`.
+     *
      * @return {object}
+     *   A map of events.
      */
     events: function () {
       // Prevents delay and simulated mouse events.
@@ -35,7 +38,9 @@
      * @augments Backbone.View
      *
      * @param {object} options
+     *   Options for the view object.
      * @param {object} options.strings
+     *   Various strings to use in the view.
      */
     initialize: function (options) {
       this.strings = options.strings;
@@ -58,6 +63,7 @@
      * @inheritdoc
      *
      * @return {Drupal.toolbar.ToolbarVisualView}
+     *   The `ToolbarVisualView` instance.
      */
     render: function () {
       this.updateTabs();
@@ -91,6 +97,7 @@
      * Responds to a toolbar tab click.
      *
      * @param {jQuery.Event} event
+     *   The event triggered.
      */
     onTabClick: function (event) {
       // If this tab has a tray associated with it, it is considered an
@@ -111,6 +118,7 @@
      * Toggles the orientation of a toolbar tray.
      *
      * @param {jQuery.Event} event
+     *   The event triggered.
      */
     onOrientationToggleClick: function (event) {
       var orientation = this.model.get('orientation');