From 7ecd6b9ce64ed54b4c893e17c8da0726702a5ab2 Mon Sep 17 00:00:00 2001
From: Thiemo Kreuz <thiemo.kreuz@wikimedia.de>
Date: Wed, 23 Jan 2019 22:01:07 +0100
Subject: [PATCH] Document Uri.js constructor and methods throwing Errors

I, personally, think the fact an empty `new Uri()` call can fail with
an Error being thrown is a bug. But it seems others think this is a
feature (see Ib4dc568). Can we at least document it then? And then
somehow (not sure how) tell everybody who ever used this class to fix
their code?

Change-Id: I86ef1ccf90f9be9c61bc6a8312369ae09d622b0c
---
 resources/src/mediawiki.Uri/Uri.js | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/resources/src/mediawiki.Uri/Uri.js b/resources/src/mediawiki.Uri/Uri.js
index 0e5a5ba9c8..385604df74 100644
--- a/resources/src/mediawiki.Uri/Uri.js
+++ b/resources/src/mediawiki.Uri/Uri.js
@@ -95,7 +95,7 @@
 	 *
 	 * @private
 	 * @static
-	 * @property {Array} properties
+	 * @property {string[]} properties
 	 */
 	properties = [
 		'protocol',
@@ -134,14 +134,14 @@
 	 */
 
 	/**
-	 * A factory method to create a Uri class with a default location to resolve relative URLs
+	 * A factory method to create an mw.Uri class with a default location to resolve relative URLs
 	 * against (including protocol-relative URLs).
 	 *
 	 * @method
 	 * @param {string|Function} documentLocation A full url, or function returning one.
 	 *  If passed a function, the return value may change over time and this will be honoured. (T74334)
 	 * @member mw
-	 * @return {Function} Uri class
+	 * @return {Function} An mw.Uri class constructor
 	 */
 	mw.UriRelative = function ( documentLocation ) {
 		var getDefaultUri = ( function () {
@@ -176,6 +176,7 @@
 		 * @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`).
+		 * @throws {Error} when the query string or fragment contains an unknown % sequence
 		 */
 		function Uri( uri, options ) {
 			var prop, hrefCur,
@@ -266,6 +267,7 @@
 		 * @static
 		 * @param {string} s String to decode
 		 * @return {string} Decoded string
+		 * @throws {Error} when the string contains an unknown % sequence
 		 */
 		Uri.decode = function ( s ) {
 			return decodeURIComponent( s.replace( /\+/g, '%20' ) );
@@ -279,6 +281,7 @@
 			 * @private
 			 * @param {string} str URI, see constructor.
 			 * @param {Object} options See constructor.
+			 * @throws {Error} when the query string or fragment contains an unknown % sequence
 			 */
 			parse: function ( str, options ) {
 				var q, matches,
-- 
2.20.1