Merge "Documentation: Port mw.Uri to JSDoc"
This commit is contained in:
jenkins-bot
Gerrit Code Review
commit
1e83812456
2 changed files with 67 additions and 66 deletions
5
jsdoc.js
5
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',
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue