From a9f2f2da2dc763d65454a4c012b019333749eeb6 Mon Sep 17 00:00:00 2001 From: lwatson Date: Wed, 13 Dec 2023 10:19:03 -0500 Subject: [PATCH] Documentation: Port mw.Uri to JSDoc Bug: T352308 Change-Id: If780d42c77ac270046ac19a534c758ef2e6f7215 --- jsdoc.js | 5 +- resources/src/mediawiki.Uri/Uri.js | 128 ++++++++++++++--------------- 2 files changed, 67 insertions(+), 66 deletions(-) diff --git a/jsdoc.js b/jsdoc.js index f7ec7f623ff..e3130303754 100644 --- a/jsdoc.js +++ b/jsdoc.js @@ -21,7 +21,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 @@ -50,7 +52,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', diff --git a/resources/src/mediawiki.Uri/Uri.js b/resources/src/mediawiki.Uri/Uri.js index 5e05e0568f8..b26fbb8c81a 100644 --- a/resources/src/mediawiki.Uri/Uri.js +++ b/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 , MIT License. - * - * - * @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 , MIT License. + * + * * 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