mw.toolbar: Clean up code and jsduckify

* Removed remnants of the 7th 'selectText' parameter. This
  was still tossed around in a few places, but in the function
  it ends up in (toolbar.insertTags) it is no longer used.
* Per code conventions, don't use jQuery's magic attrMap
  argument, instead call the (in this case attr) method directly.
* Optimise way we get the reference to the detached Array#slice,
  access 'slice' on local array instead of global variabile
  lookup for 'Array' and accessing prototype (learned from jQuery core).
* Link "mw.toolbar.addButton" is invalid in jsduck, members
  of modules are accessed by a hash sign. Should be
  "mw.toolbar#addButton" or even just #addButton in this case.
* Eliminated scrollEditBox function by inlining its contents into the
  $( document ).ready handler.

Change-Id: I867f2bcfd97e00a498a963e5d9730e5b0d36dcae

diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json
index df927b3..962b082 100644 (file)
--- a/maintenance/jsduck/categories.json
+++ b/maintenance/jsduck/categories.json
@@ -26,6 +26,10 @@
                                        "mw.plugin.*"
                                ]
                        },
+                       {
+                               "name": "Actions",
+                               "classes": ["mw.toolbar"]
+                       },
                        {
                                "name": "API",
                                "classes": ["mw.Api*"]

diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json
index 46033fc..60522c5 100644 (file)
--- a/maintenance/jsduck/config.json
+++ b/maintenance/jsduck/config.json
@@ -15,6 +15,7 @@
                "../../resources/mediawiki/mediawiki.notify.js",
                "../../resources/mediawiki/mediawiki.notification.js",
                "../../resources/mediawiki/mediawiki.user.js",
+               "../../resources/mediawiki.action/mediawiki.action.edit.js",
                "../../resources/mediawiki.api",
                "../../resources/jquery/jquery.localize.js"
        ]

diff --git a/resources/mediawiki.action/mediawiki.action.edit.js b/resources/mediawiki.action/mediawiki.action.edit.js
index fc1b18d..1c5a018 100644 (file)
--- a/resources/mediawiki.action/mediawiki.action.edit.js
+++ b/resources/mediawiki.action/mediawiki.action.edit.js
@@ -1,17 +1,20 @@
+/**
+ * Interface for the classic edit toolbar.
+ *
+ * @class mw.toolbar
+ * @singleton
+ */
 ( function ( mw, $ ) {
-       var isReady, toolbar, currentFocused, queue, $toolbar, slice;
-
-       isReady = false;
-       queue = [];
-       $toolbar = false;
-       slice = Array.prototype.slice;
+       var toolbar, isReady, $toolbar, queue, slice, currentFocused;
 
        /**
-        * Internal helper that does the actual insertion
-        * of the button into the toolbar.
-        * See mw.toolbar.addButton for parameter documentation.
+        * Internal helper that does the actual insertion of the button into the toolbar.
+        *
+        * See #addButton for parameter documentation.
+        *
+        * @private
         */
-       function insertButton( b /* imageFile */, speedTip, tagOpen, tagClose, sampleText, imageId, selectText ) {
+       function insertButton( b, speedTip, tagOpen, tagClose, sampleText, imageId ) {
                // Backwards compatibility
                if ( typeof b !== 'object' ) {
                        b = {
@@ -20,11 +23,10 @@
                                tagOpen: tagOpen,
                                tagClose: tagClose,
                                sampleText: sampleText,
-                               imageId: imageId,
-                               selectText: selectText
+                               imageId: imageId
                        };
                }
-               var $image = $( '<img>', {
+               var $image = $( '<img>' ).attr( {
                        width : 23,
                        height: 22,
                        src   : b.imageFile,
@@ -33,30 +35,37 @@
                        id    : b.imageId || undefined,
                        'class': 'mw-toolbar-editbutton'
                } ).click( function () {
-                       toolbar.insertTags( b.tagOpen, b.tagClose, b.sampleText, b.selectText );
+                       toolbar.insertTags( b.tagOpen, b.tagClose, b.sampleText );
                        return false;
                } );
 
                $toolbar.append( $image );
-               return true;
        }
 
+       isReady = false;
+       $toolbar = false;
+       queue = [];
+       slice = queue.slice;
+
        toolbar = {
+
                /**
                 * Add buttons to the toolbar.
+                *
                 * Takes care of race conditions and time-based dependencies
                 * by placing buttons in a queue if this method is called before
                 * the toolbar is created.
-                * @param {Object} button: Object with the following properties:
-                * - imageFile
-                * - speedTip
-                * - tagOpen
-                * - tagClose
-                * - sampleText
-                * - imageId
-                * - selectText
-                * For compatiblity, passing the above as separate arguments
+                *
+                * For compatiblity, passing the properties listed below as separate arguments
                 * (in the listed order) is also supported.
+                *
+                * @param {Object} button Object with the following properties:
+                * @param {string} button.imageFile
+                * @param {string} button.speedTip
+                * @param {string} button.tagOpen
+                * @param {string} button.tagClose
+                * @param {string} button.sampleText
+                * @param {string} [button.imageId]
                 */
                addButton: function () {
                        if ( isReady ) {
@@ -68,8 +77,13 @@
                },
 
                /**
-                * Apply tagOpen/tagClose to selection in textarea,
-                * use sampleText instead of selection if there is none.
+                * Apply tagOpen/tagClose to selection in currently focused textarea.
+                *
+                * Uses `sampleText` if selection is empty.
+                *
+                * @param {string} tagOpen
+                * @param {string} tagClose
+                * @param {string} sampleText
                 */
                insertTags: function ( tagOpen, tagClose, sampleText ) {
                        if ( currentFocused && currentFocused.length ) {
@@ -96,7 +110,7 @@
        mw.toolbar = toolbar;
 
        $( document ).ready( function () {
-               var buttons, i, b, $iframe;
+               var buttons, i, b, $iframe, editBox, scrollTop, $editForm;
 
                // currentFocus is used to determine where to insert tags
                currentFocused = $( '#wpTextbox1' );
@@ -128,25 +142,19 @@
                // Make sure edit summary does not exceed byte limit
                $( '#wpSummary' ).byteLimit( 255 );
 
-               /**
-                * Restore the edit box scroll state following a preview operation,
-                * and set up a form submission handler to remember this state
-                */
-               ( function scrollEditBox() {
-                       var editBox, scrollTop, $editForm;
-
-                       editBox = document.getElementById( 'wpTextbox1' );
-                       scrollTop = document.getElementById( 'wpScrolltop' );
-                       $editForm = $( '#editform' );
-                       if ( $editForm.length && editBox && scrollTop ) {
-                               if ( scrollTop.value ) {
-                                       editBox.scrollTop = scrollTop.value;
-                               }
-                               $editForm.submit( function () {
-                                       scrollTop.value = editBox.scrollTop;
-                               });
+               // Restore the edit box scroll state following a preview operation,
+               // and set up a form submission handler to remember this state.
+               editBox = document.getElementById( 'wpTextbox1' );
+               scrollTop = document.getElementById( 'wpScrolltop' );
+               $editForm = $( '#editform' );
+               if ( $editForm.length && editBox && scrollTop ) {
+                       if ( scrollTop.value ) {
+                               editBox.scrollTop = scrollTop.value;
                        }
-               }() );
+                       $editForm.submit( function () {
+                               scrollTop.value = editBox.scrollTop;
+                       });
+               }
 
                // Apply to dynamically created textboxes as well as normal ones
                $( document ).on( 'focus', 'textarea, input:text', function () {