mediawiki.page.gallery: Improve documentation

This file does a lot of things, but the header starts with
explaining a random/obscure thing it does with 4 lines of code
at the end of this large file.

Move that explanation near that actual code. Presumably it was
placed at the top because it used to be the only thing the
file was responsible for.

Change-Id: I75299a25dd8f5f4d4ab4cdc8fc90d74e6a74422c

diff --git a/resources/src/mediawiki.page.gallery.js b/resources/src/mediawiki.page.gallery.js
index 79937e5..9448ab8 100644 (file)
--- a/resources/src/mediawiki.page.gallery.js
+++ b/resources/src/mediawiki.page.gallery.js
@@ -1,6 +1,8 @@
 /*!
- * Show gallery captions when focused. Copied directly from jquery.mw-jump.js.
- * Also Dynamically resize images to justify them.
+ * Enhance MediaWiki galleries (from the `<gallery>` parser tag).
+ *
+ * - Toggle gallery captions when focused.
+ * - Dynamically resize images to fill horizontal space.
  */
 ( function ( mw, $ ) {
        var $galleries,
@@ -242,8 +244,9 @@
                                .addClass( 'mw-gallery-packed-overlay' )
                                .removeClass( 'mw-gallery-packed-hover' );
                } else {
-                       // Note use of just "a", not a.image, since we want this to trigger if a link in
-                       // the caption receives focus
+                       // Note use of just `a`, not `a.image`, since we also want this to trigger if a link
+                       // within the caption text receives focus.
+                       // This is based on code from the 'jquery.mw-jump' module.
                        $content.find( 'ul.mw-gallery-packed-hover li.gallerybox' ).on( 'focus blur', 'a', function ( e ) {
                                // Confusingly jQuery leaves e.type as focusout for delegated blur events
                                var gettingFocus = e.type !== 'blur' && e.type !== 'focusout';