From 6d1c3e5ffcbba39ed2c83cf28f2b7215c08befd5 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Mon, 9 Apr 2018 10:59:15 -0700
Subject: [PATCH] doc: clarify url doc

Indicate that `base` is ignored if `input` is absolute.

PR-URL: https://github.com/nodejs/node/pull/19899
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
---
 doc/api/url.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/doc/api/url.md b/doc/api/url.md
index e1e6c0133ee27e..97cc284a6d500c 100644
--- a/doc/api/url.md
+++ b/doc/api/url.md
@@ -93,7 +93,9 @@ return `true`.
 
 #### Constructor: new URL(input[, base])
 
-* `input` {string} The input URL to parse
+* `input` {string} The absolute or relative input URL to parse. If `input`
+  is relative, then `base` is required. If `input` is absolute, the `base`
+  is ignored.
 * `base` {string|URL} The base URL to resolve against if the `input` is not
   absolute.
 
@@ -125,6 +127,32 @@ const myURL = new URL('https://你好你好');
 This feature is only available if the `node` executable was compiled with
 [ICU][] enabled. If not, the domain names are passed through unchanged.
 
+In cases where it is not known in advance if `input` is an absolute URL
+and a `base` is provided, it is advised to validate that the `origin` of
+the `URL` object is what is expected.
+
+```js
+const { URL } = require('url');
+
+let myURL = new URL('http://anotherExample.org/', 'https://example.org/');
+// http://anotherexample.org/
+
+myURL = new URL('https://anotherExample.org/', 'https://example.org/');
+// https://anotherexample.org/
+
+myURL = new URL('foo://anotherExample.org/', 'https://example.org/');
+// foo://anotherExample.org/
+
+myURL = new URL('http:anotherExample.org/', 'https://example.org/');
+// http://anotherexample.org/
+
+myURL = new URL('https:anotherExample.org/', 'https://example.org/');
+// https://example.org/anotherExample.org/
+
+myURL = new URL('foo:anotherExample.org/', 'https://example.org/');
+// foo:anotherExample.org/
+```
+
 #### url.hash
 
 * {string}