From 657ff95613f1157ee355aa2c8de189ecdf348ba6 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Bartosz=20Dziewo=C5=84ski?= <matma.rex@gmail.com>
Date: Mon, 5 Feb 2018 16:54:28 +0100
Subject: [PATCH] jquery.textSelection: Document methods and parameters

Change-Id: I9e4112a75ae7abc8c479efc39a438c3b59933418
---
 jsduck.json                                  |   1 +
 resources/src/jquery/jquery.textSelection.js | 154 +++++++++++++++----
 2 files changed, 124 insertions(+), 31 deletions(-)

diff --git a/jsduck.json b/jsduck.json
index 0021f37676..0a48be334c 100644
--- a/jsduck.json
+++ b/jsduck.json
@@ -34,6 +34,7 @@
 		"resources/src/jquery/jquery.spinner.js",
 		"resources/src/jquery/jquery.suggestions.js",
 		"resources/src/jquery/jquery.tabIndex.js",
+		"resources/src/jquery/jquery.textSelection.js",
 		"resources/lib/jquery.client/jquery.client.js",
 		"resources/lib/oojs/oojs.jquery.js",
 		"resources/lib/oojs-ui/oojs-ui-core.js",
diff --git a/resources/src/jquery/jquery.textSelection.js b/resources/src/jquery/jquery.textSelection.js
index dc9d4cfc2c..3891d6d0e3 100644
--- a/resources/src/jquery/jquery.textSelection.js
+++ b/resources/src/jquery/jquery.textSelection.js
@@ -1,4 +1,4 @@
-/**
+/*!
  * These plugins provide extra functionality for interaction with textareas.
  *
  * - encapsulateSelection: Ported from skins/common/edit.js by Trevor Parscal
@@ -7,7 +7,42 @@
  *   https://github.com/Wikia/app/blob/c0cd8b763/extensions/wikia/LinkSuggest/js/jquery.wikia.linksuggest.js
  *   © 2010 Inez Korczyński (korczynski@gmail.com) & Jesús Martínez Novo (martineznovo@gmail.com) (GPLv2)
  */
+
+/**
+ * @class jQuery.plugin.textSelection
+ *
+ * Do things to the selection in a `<textarea>`, or a textarea-like editable element.
+ *
+ *     var $textbox = $( '#wpTextbox1' );
+ *     $textbox.textSelection( 'setContents', 'This is bold!' );
+ *     $textbox.textSelection( 'setSelection', { start: 8, end: 12 } );
+ *     $textbox.textSelection( 'encapsulateSelection', { pre: '<b>', post: '</b>' } );
+ *     // Result: Textbox contains 'This is <b>bold</b>!', with cursor before the '!'
+ */
 ( function ( $ ) {
+	/**
+	 * Do things to the selection in a `<textarea>`, or a textarea-like editable element.
+	 *
+	 *     var $textbox = $( '#wpTextbox1' );
+	 *     $textbox.textSelection( 'setContents', 'This is bold!' );
+	 *     $textbox.textSelection( 'setSelection', { start: 8, end: 12 } );
+	 *     $textbox.textSelection( 'encapsulateSelection', { pre: '<b>', post: '</b>' } );
+	 *     // Result: Textbox contains 'This is <b>bold</b>!', with cursor before the '!'
+	 *
+	 * @param {string} command Command to execute, one of:
+	 *
+	 *  - {@link jQuery.plugin.textSelection#getContents getContents}
+	 *  - {@link jQuery.plugin.textSelection#setContents setContents}
+	 *  - {@link jQuery.plugin.textSelection#getSelection getSelection}
+	 *  - {@link jQuery.plugin.textSelection#encapsulateSelection encapsulateSelection}
+	 *  - {@link jQuery.plugin.textSelection#getCaretPosition getCaretPosition}
+	 *  - {@link jQuery.plugin.textSelection#setSelection setSelection}
+	 *  - {@link jQuery.plugin.textSelection#scrollToCaretPosition scrollToCaretPosition}
+	 *  - {@link jQuery.plugin.textSelection#register register}
+	 *  - {@link jQuery.plugin.textSelection#unregister unregister}
+	 * @param {Mixed} [options] Options to pass to the command
+	 * @return {Mixed} Depending on the command
+	 */
 	$.fn.textSelection = function ( command, options ) {
 		var fn,
 			alternateFn,
@@ -15,24 +50,29 @@
 
 		fn = {
 			/**
-			 * Get the contents of the textarea
+			 * Get the contents of the textarea.
 			 *
+			 * @private
 			 * @return {string}
 			 */
 			getContents: function () {
 				return this.val();
 			},
+
 			/**
-			 * Set the contents of the textarea, replacing anything that was there before
+			 * Set the contents of the textarea, replacing anything that was there before.
 			 *
+			 * @private
 			 * @param {string} content
 			 */
 			setContents: function ( content ) {
 				this.val( content );
 			},
+
 			/**
 			 * Get the currently selected text in this textarea.
 			 *
+			 * @private
 			 * @return {string}
 			 */
 			getSelection: function () {
@@ -47,13 +87,29 @@
 
 				return retval;
 			},
+
 			/**
-			 * Inserts text at the beginning and end of a text selection, optionally
+			 * Insert text at the beginning and end of a text selection, optionally
 			 * inserting text at the caret when selection is empty.
 			 *
-			 * @param {Object} options Options
-			 * FIXME document the options parameters
+			 * Also focusses the textarea.
+			 *
+			 * @private
+			 * @param {Object} [options]
+			 * @param {string} [options.pre] Text to insert before the cursor/selection
+			 * @param {string} [options.peri] Text to insert between pre and post and select afterwards
+			 * @param {string} [options.post] Text to insert after the cursor/selection
+			 * @param {boolean} [options.ownline=false] Put the inserted text on a line of its own
+			 * @param {boolean} [options.replace=false] If there is a selection, replace it with peri
+			 *  instead of leaving it alone
+			 * @param {boolean} [options.selectPeri=true] Select the peri text if it was inserted (but not
+			 *  if there was a selection and replace==false, or if splitlines==true)
+			 * @param {boolean} [options.splitlines=false] If multiple lines are selected, encapsulate
+			 *  each line individually
+			 * @param {number} [options.selectionStart] Position to start selection at
+			 * @param {number} [options.selectionEnd=options.selectionStart] Position to end selection at
 			 * @return {jQuery}
+			 * @chainable
 			 */
 			encapsulateSelection: function ( options ) {
 				return this.each( function () {
@@ -63,6 +119,7 @@
 						post = options.post;
 
 					/**
+					 * @ignore
 					 * Check if the selected text is the same as the insert text
 					 */
 					function checkSelectedText() {
@@ -86,6 +143,7 @@
 					}
 
 					/**
+					 * @ignore
 					 * Do the splitlines stuff.
 					 *
 					 * Wrap each line of the selected text with pre and post
@@ -168,13 +226,16 @@
 						options.replace, options.splitlines ] );
 				} );
 			},
+
 			/**
-			 * Get the position (in resolution of bytes not necessarily characters)
-			 * in a textarea
+			 * Get the current cursor position (in UTF-16 code units) in a textarea.
 			 *
-			 * @param {Object} options Options
-			 * FIXME document the options parameters
-			 * @return {number} Position
+			 * @private
+			 * @param {Object} [options]
+			 * @param {Object} [options.startAndEnd=false] Return range of the selection rather than just start
+			 * @return {Mixed}
+			 *  - When `startAndEnd` is `false`: number
+			 *  - When `startAndEnd` is `true`: array with two numbers, for start and end of selection
 			 */
 			getCaretPosition: function ( options ) {
 				function getCaret( e ) {
@@ -189,10 +250,16 @@
 				}
 				return getCaret( this.get( 0 ) );
 			},
+
 			/**
-			 * @param {Object} options options
-			 * FIXME document the options parameters
+			 * Set the current cursor position (in UTF-16 code units) in a textarea.
+			 *
+			 * @private
+			 * @param {Object} [options]
+			 * @param {number} options.start
+			 * @param {number} [options.end=options.start]
 			 * @return {jQuery}
+			 * @chainable
 			 */
 			setSelection: function ( options ) {
 				return this.each( function () {
@@ -213,15 +280,17 @@
 					}
 				} );
 			},
+
 			/**
 			 * Scroll a textarea to the current cursor position. You can set the cursor
-			 * position with setSelection()
+			 * position with #setSelection.
 			 *
-			 * @param {Object} options options
-			 * @cfg {boolean} [force=false] Whether to force a scroll even if the caret position
+			 * @private
+			 * @param {Object} [options]
+			 * @param {string} [options.force=false] Whether to force a scroll even if the caret position
 			 *  is already visible.
-			 * FIXME document the options parameters
 			 * @return {jQuery}
+			 * @chainable
 			 */
 			scrollToCaretPosition: function ( options ) {
 				function getLineLength( e ) {
@@ -290,6 +359,25 @@
 			}
 		};
 
+		/**
+		 * @method register
+		 *
+		 * Register an alternative textSelection API for this element.
+		 *
+		 * @private
+		 * @param {Object} functions Functions to replace. Keys are command names (as in #textSelection,
+		 *  except 'register' and 'unregister'). Values are functions to execute when a given command is
+		 *  called.
+		 */
+
+		/**
+		 * @method unregister
+		 *
+		 * Unregister the alternative textSelection API for this element (see #register).
+		 *
+		 * @private
+		 */
+
 		alternateFn = $( this ).data( 'jquery.textSelection' );
 
 		// Apply defaults
@@ -299,38 +387,34 @@
 			// case 'getSelection': // no params
 			case 'encapsulateSelection':
 				options = $.extend( {
-					pre: '', // Text to insert before the cursor/selection
-					peri: '', // Text to insert between pre and post and select afterwards
-					post: '', // Text to insert after the cursor/selection
-					ownline: false, // Put the inserted text on a line of its own
-					replace: false, // If there is a selection, replace it with peri instead of leaving it alone
-					selectPeri: true, // Select the peri text if it was inserted (but not if there was a selection and replace==false, or if splitlines==true)
-					splitlines: false, // If multiple lines are selected, encapsulate each line individually
-					selectionStart: undefined, // Position to start selection at
-					selectionEnd: undefined // Position to end selection at. Defaults to start
+					pre: '',
+					peri: '',
+					post: '',
+					ownline: false,
+					replace: false,
+					selectPeri: true,
+					splitlines: false,
+					selectionStart: undefined,
+					selectionEnd: undefined
 				}, options );
 				break;
 			case 'getCaretPosition':
 				options = $.extend( {
-					// Return [start, end] instead of just start
 					startAndEnd: false
 				}, options );
 				break;
 			case 'setSelection':
 				options = $.extend( {
-					// Position to start selection at
 					start: undefined,
-					// Position to end selection at. Defaults to start
 					end: undefined
 				}, options );
-
 				if ( options.end === undefined ) {
 					options.end = options.start;
 				}
 				break;
 			case 'scrollToCaretPosition':
 				options = $.extend( {
-					force: false // Force a scroll even if the caret position is already visible
+					force: false
 				}, options );
 				break;
 			case 'register':
@@ -351,4 +435,12 @@
 		return retval;
 	};
 
+	/**
+	 * @class jQuery
+	 */
+	/**
+	 * @method textSelection
+	 * @inheritdoc jQuery.plugin.textSelection#textSelection
+	 */
+
 }( jQuery ) );
-- 
2.20.1