Merge "Documentation: Port mw.Uri to JSDoc"

jsdoc.js

@@ -23,7 +23,9 @@ module.exports = {
 			'resources/src/mediawiki.experiments.js',
 			'resources/src/mediawiki.notification',
 			'resources/src/mediawiki.util',
-			'resources/src/startup'
+			'resources/src/startup',
+			'resources/src/mediawiki.Uri'
+
 		],
 		exclude: [
 			/* The following modules are temporarily disabled as we haven't
@@ -52,7 +54,6 @@ module.exports = {
 			'resources/src/mediawiki.special.apisandbox',
 			'resources/src/mediawiki.Upload.js',
 			'resources/src/mediawiki.special.block.js',
-			'resources/src/mediawiki.Uri',
 			'resources/src/mediawiki.special.changecredentails.js',
 			'resources/src/mediawiki.action',
 			'resources/src/mediawiki.special.changeemail.js',

resources/src/mediawiki.Uri/Uri.js

@@ -1,55 +1,3 @@
-/**
- * Library for simple URI parsing and manipulation.
- *
- * Intended to be minimal, but featureful; do not expect full RFC 3986 compliance. The use cases we
- * have in mind are constructing 'next page' or 'previous page' URLs, detecting whether we need to
- * use cross-domain proxies for an API, constructing simple URL-based API calls, etc. Parsing here
- * is regex-based, so may not work on all URIs, but is good enough for most.
- *
- * You can modify the properties directly, then use the #toString method to extract the full URI
- * string again. Example:
- *
- *     var uri = new mw.Uri( 'http://example.com/mysite/mypage.php?quux=2' );
- *
- *     if ( uri.host == 'example.com' ) {
- *         uri.host = 'foo.example.com';
- *         uri.extend( { bar: 1 } );
- *
- *         $( 'a#id1' ).attr( 'href', uri );
- *         // anchor with id 'id1' now links to http://foo.example.com/mysite/mypage.php?bar=1&quux=2
- *
- *         $( 'a#id2' ).attr( 'href', uri.clone().extend( { bar: 3, pif: 'paf' } ) );
- *         // anchor with id 'id2' now links to http://foo.example.com/mysite/mypage.php?bar=3&quux=2&pif=paf
- *     }
- *
- * Given a URI like
- * `http://usr:pwd@www.example.com:81/dir/dir.2/index.htm?q1=0&&test1&test2=&test3=value+%28escaped%29&r=1&r=2#top`
- * the returned object will have the following properties:
- *
- *     protocol  'http'
- *     user      'usr'
- *     password  'pwd'
- *     host      'www.example.com'
- *     port      '81'
- *     path      '/dir/dir.2/index.htm'
- *     query     {
- *                   q1: '0',
- *                   test1: null,
- *                   test2: '',
- *                   test3: 'value (escaped)'
- *                   r: ['1', '2']
- *               }
- *     fragment  'top'
- *
- * (N.b., 'password' is technically not allowed for HTTP URIs, but it is possible with other kinds
- * of URIs.)
- *
- * Parsing based on parseUri 1.2.2 (c) Steven Levithan <http://stevenlevithan.com>, MIT License.
- * <http://stevenlevithan.com/demo/parseuri/js/>
- *
- * @class mw.Uri
- */
-
 ( function () {
 	var parser, properties;
 
@@ -134,7 +82,7 @@
 	 */
 
 	/**
-	 * A factory method to create an mw.Uri class with a default location to resolve relative URLs
+	 * A factory method to create an {@link mw.Uri} class with a default location to resolve relative URLs
 	 * against (including protocol-relative URLs).
 	 *
 	 * @method
@@ -158,27 +106,79 @@
 				return uri;
 			};
 		}() );
+		/**
+		 * @typedef {Object} mw.Uri.UriOptions
+		 * @property {boolean} [strictMode=false] Trigger strict mode parsing of the url.
+		 * @property {boolean} [overrideKeys=false] Whether to let duplicate query parameters
+		 *  override each other (`true`) or automagically convert them to an array (`false`).
+		 * @property {boolean} [arrayParams=false] Whether to parse array query parameters (e.g.
+		 *  `&foo[0]=a&foo[1]=b` or `&foo[]=a&foo[]=b`) or leave them alone. Currently this does not
+		 *  handle associative or multi-dimensional arrays, but that may be improved in the future.
+		 *  Implies `overrideKeys: true` (query parameters without `[...]` are not parsed as arrays).
+		 */
 
 		/**
+		 * @classdesc
+		 * Library for simple URI parsing and manipulation.
+		 *
+		 * Intended to be minimal, but featureful; do not expect full RFC 3986 compliance. The use cases we
+		 * have in mind are constructing 'next page' or 'previous page' URLs, detecting whether we need to
+		 * use cross-domain proxies for an API, constructing simple URL-based API calls, etc. Parsing here
+		 * is regex-based, so may not work on all URIs, but is good enough for most.
+		 *
+		 * You can modify the properties directly, then use the {@link mw.Uri#toString toString} method to extract the full URI
+		 * string again. Example:
+		 *
+		 *     var uri = new mw.Uri( 'http://example.com/mysite/mypage.php?quux=2' );
+		 *
+		 *     if ( uri.host == 'example.com' ) {
+		 *         uri.host = 'foo.example.com';
+		 *         uri.extend( { bar: 1 } );
+		 *
+		 *         $( 'a#id1' ).attr( 'href', uri );
+		 *         // anchor with id 'id1' now links to http://foo.example.com/mysite/mypage.php?bar=1&quux=2
+		 *
+		 *         $( 'a#id2' ).attr( 'href', uri.clone().extend( { bar: 3, pif: 'paf' } ) );
+		 *         // anchor with id 'id2' now links to http://foo.example.com/mysite/mypage.php?bar=3&quux=2&pif=paf
+		 *     }
+		 *
+		 * Given a URI like
+		 * `http://usr:pwd@www.example.com:81/dir/dir.2/index.htm?q1=0&&test1&test2=&test3=value+%28escaped%29&r=1&r=2#top`
+		 * the returned object will have the following properties:
+		 *
+		 *     protocol  'http'
+		 *     user      'usr'
+		 *     password  'pwd'
+		 *     host      'www.example.com'
+		 *     port      '81'
+		 *     path      '/dir/dir.2/index.htm'
+		 *     query     {
+		 *                   q1: '0',
+		 *                   test1: null,
+		 *                   test2: '',
+		 *                   test3: 'value (escaped)'
+		 *                   r: ['1', '2']
+		 *               }
+		 *     fragment  'top'
+		 *
+		 * (N.b., 'password' is technically not allowed for HTTP URIs, but it is possible with other kinds
+		 * of URIs.)
+		 *
+		 * Parsing based on parseUri 1.2.2 (c) Steven Levithan <http://stevenlevithan.com>, MIT License.
+		 * <http://stevenlevithan.com/demo/parseuri/js/>
+		 *
 		 * Construct a new URI object. Throws error if arguments are illegal/impossible, or
 		 * otherwise don't parse.
 		 *
-		 * @class mw.Uri
+		 * @memberof mw
 		 * @constructor
 		 * @param {Object|string} [uri] URI string, or an Object with appropriate properties (especially
 		 *  another URI object to clone). Object must have non-blank `protocol`, `host`, and `path`
 		 *  properties. If omitted (or set to `undefined`, `null` or empty string), then an object
 		 *  will be created for the default `uri` of this constructor (`location.href` for mw.Uri,
 		 *  other values for other instances -- see mw.UriRelative for details).
-		 * @param {Object|boolean} [options] Object with options, or (backwards compatibility) a boolean
+		 * @param {mw.Uri.UriOptions|boolean} [options] Object with options, or (backwards compatibility) a boolean
 		 *  for strictMode
-		 * @param {boolean} [options.strictMode=false] Trigger strict mode parsing of the url.
-		 * @param {boolean} [options.overrideKeys=false] Whether to let duplicate query parameters
-		 *  override each other (`true`) or automagically convert them to an array (`false`).
-		 * @param {boolean} [options.arrayParams=false] Whether to parse array query parameters (e.g.
-		 *  `&foo[0]=a&foo[1]=b` or `&foo[]=a&foo[]=b`) or leave them alone. Currently this does not
-		 *  handle associative or multi-dimensional arrays, but that may be improved in the future.
-		 *  Implies `overrideKeys: true` (query parameters without `[...]` are not parsed as arrays).
 		 * @throws {Error} when the query string or fragment contains an unknown % sequence
 		 */
 		function Uri( uri, options ) {
@@ -251,7 +251,7 @@
 		 *
 		 * Standard encodeURIComponent, with extra stuff to make all browsers work similarly and more
 		 * compliant with RFC 3986. Similar to rawurlencode from PHP and our JS library
-		 * mw.util.rawurlencode, except this also replaces spaces with `+`.
+		 * {@link mediawiki.module:util.rawurlencode mw.util.rawurlencode}, except this also replaces spaces with `+`.
 		 *
 		 * @static
 		 * @param {string} s String to encode
@@ -267,7 +267,7 @@
 		/**
 		 * Decode a url encoded value.
 		 *
-		 * Reversed #encode. Standard decodeURIComponent, with addition of replacing
+		 * Reversed {@link mw.Uri.encode encode}. Standard decodeURIComponent, with addition of replacing
 		 * `+` with a space.
 		 *
 		 * @static