diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index c3cbef224c0f45..7cbaa4274da276 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -30,7 +30,7 @@ const packages = [
//'redux-routine',
'rich-text',
'shortcode',
- //'url',
+ 'url',
'viewport',
//'wordcount',
];
diff --git a/packages/url/README.md b/packages/url/README.md
index fb78d8808bb2be..611efcddfc3f3b 100644
--- a/packages/url/README.md
+++ b/packages/url/README.md
@@ -14,173 +14,401 @@ _This package assumes that your code will run in an **ES2015+** environment. If
## Usage
-### isURL
+
-```js
-const isURL = isURL( 'https://wordpress.org' ); // true
-```
+### addQueryArgs
-Checks whether the URL is an HTTP or HTTPS URL.
+[src/index.js#L242-L264](src/index.js#L242-L264)
+Appends arguments as querystring to the provided URL. If the URL already
+includes query arguments, the arguments are merged with (and take precedent
+over) the existing set.
-### getProtocol
+**Usage**
```js
-const protocol1 = getProtocol( 'tel:012345678' ); // 'tel:'
-const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:'
+const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://google.com/?q=test
```
-Returns the protocol part of the provided URL.
+**Parameters**
+- **url** `?string`: URL to which arguments should be appended. If omitted, only the resulting querystring is returned.
+- **args** `Object`: Query arguments to apply to URL.
-### isValidProtocol
+**Returns**
+
+`string`: URL with arguments applied.
+
+### filterURLForDisplay
+
+[src/index.js#L379-L389](src/index.js#L379-L389)
+
+Returns a URL for display.
+
+**Usage**
```js
-const isValid = isValidProtocol( 'https:' ); // true
-const isNotValid = isValidProtocol( 'https :' ); // false
+const displayUrl = filterURLForDisplay( 'https://www.wordpress.org/gutenberg/' ); // wordpress.org/gutenberg
```
-Returns true if the provided protocol is valid. Returns false if the protocol contains invalid characters.
+**Parameters**
+
+- **url** `string`: Original URL.
+
+**Returns**
+`string`: Displayed URL.
### getAuthority
+[src/index.js#L79-L84](src/index.js#L79-L84)
+
+Returns the authority part of the URL.
+
+**Usage**
+
```js
const authority1 = getAuthority( 'https://wordpress.org/help/' ); // 'wordpress.org'
const authority2 = getAuthority( 'https://localhost:8080/test/' ); // 'localhost:8080'
```
-Returns the authority part of the provided URL.
+**Parameters**
+- **url** `string`: The full URL.
-### isValidAuthority
+**Returns**
+
+`?string`: The authority part of the URL.
+
+### getFragment
+
+[src/index.js#L199-L204](src/index.js#L199-L204)
+
+Returns the fragment part of the URL.
+
+**Usage**
```js
-const isValid = isValidAuthority( 'wordpress.org' ); // true
-const isNotValid = isValidAuthority( 'wordpress#org' ); // false
+const fragment1 = getFragment( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // '#fragment'
+const fragment2 = getFragment( 'https://wordpress.org#another-fragment?query=true' ); // '#another-fragment'
```
-Returns true if the provided authority is valid. Returns false if the protocol contains invalid characters.
+**Parameters**
+
+- **url** `string`: The full URL
+
+**Returns**
+`?string`: The fragment part of the URL.
### getPath
+[src/index.js#L119-L124](src/index.js#L119-L124)
+
+Returns the path part of the URL.
+
+**Usage**
+
```js
const path1 = getPath( 'http://localhost:8080/this/is/a/test?query=true' ); // 'this/is/a/test'
const path2 = getPath( 'https://wordpress.org/help/faq/' ); // 'help/faq'
```
-Returns the path part of the provided URL.
+**Parameters**
+- **url** `string`: The full URL.
-### isValidPath
+**Returns**
+
+`?string`: The path part of the URL.
+
+### getProtocol
+
+[src/index.js#L39-L44](src/index.js#L39-L44)
+
+Returns the protocol part of the URL.
+
+**Usage**
```js
-const isValid = isValidPath( 'test/path/' ); // true
-const isNotValid = isValidPath( '/invalid?test/path/' ); // false
+const protocol1 = getProtocol( 'tel:012345678' ); // 'tel:'
+const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:'
```
-Returns true if the provided path is valid. Returns false if the path contains invalid characters.
+**Parameters**
+
+- **url** `string`: The full URL.
+
+**Returns**
+
+`?string`: The protocol part of the URL.
+
+### getQueryArg
+
+[src/index.js#L279-L284](src/index.js#L279-L284)
+
+Returns a single query argument of the url
+
+**Usage**
+
+```js
+const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar
+```
+
+**Parameters**
+
+- **url** `string`: URL
+- **arg** `string`: Query arg name
+**Returns**
+
+`(Array|string)`: Query arg value.
### getQueryString
+[src/index.js#L159-L164](src/index.js#L159-L164)
+
+Returns the query string part of the URL.
+
+**Usage**
+
```js
const queryString1 = getQueryString( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // 'query=true'
const queryString2 = getQueryString( 'https://wordpress.org#fragment?query=false&search=hello' ); // 'query=false&search=hello'
```
-Returns the query string part of the provided URL.
+**Parameters**
+- **url** `string`: The full URL.
-### isValidQueryString
+**Returns**
+
+`?string`: The query string part of the URL.
+
+### hasQueryArg
+
+[src/index.js#L299-L301](src/index.js#L299-L301)
+
+Determines whether the URL contains a given query arg.
+
+**Usage**
```js
-const isValid = isValidQueryString( 'query=true&another=false' ); // true
-const isNotValid = isValidQueryString( 'query=true?another=false' ); // false
+const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true
```
-Returns true if the provided query string is valid. Returns false if the query string contains invalid characters.
+**Parameters**
+- **url** `string`: URL
+- **arg** `string`: Query arg name
-### getFragment
+**Returns**
+
+`boolean`: Whether or not the URL contains the query arg.
+
+### isURL
+
+[src/index.js#L22-L24](src/index.js#L22-L24)
+
+Determines whether the given string looks like a URL.
+
+**Usage**
```js
-const fragment1 = getFragment( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // '#fragment'
-const fragment2 = getFragment( 'https://wordpress.org#another-fragment?query=true' ); // '#another-fragment'
+const isURL = isURL( 'https://wordpress.org' ); // true
```
-Returns the fragment part of the provided URL.
+**Parameters**
+- **url** `string`: The string to scrutinise.
+
+**Returns**
+
+`boolean`: Whether or not it looks like a URL.
+
+### isValidAuthority
+
+[src/index.js#L99-L104](src/index.js#L99-L104)
+
+Checks for invalid characters within the provided authority.
+
+**Usage**
+
+```js
+const isValid = isValidAuthority( 'wordpress.org' ); // true
+const isNotValid = isValidAuthority( 'wordpress#org' ); // false
+```
+
+**Parameters**
+
+- **authority** `string`: A string containing the URL authority.
+
+**Returns**
+
+`boolean`: True if the argument contains a valid authority.
### isValidFragment
+[src/index.js#L219-L224](src/index.js#L219-L224)
+
+Checks for invalid characters within the provided fragment.
+
+**Usage**
+
```js
const isValid = isValidFragment( '#valid-fragment' ); // true
const isNotValid = isValidFragment( '#invalid-#fragment' ); // false
```
-Returns true if the provided fragment is valid. Returns false if the fragment contains invalid characters.
+**Parameters**
+- **fragment** `string`: The url fragment.
-### addQueryArgs
+**Returns**
+
+`boolean`: True if the argument contains a valid fragment.
+
+### isValidPath
+
+[src/index.js#L139-L144](src/index.js#L139-L144)
+
+Checks for invalid characters within the provided path.
+
+**Usage**
```js
-const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://google.com/?q=test
+const isValid = isValidPath( 'test/path/' ); // true
+const isNotValid = isValidPath( '/invalid?test/path/' ); // false
```
-Adds a query string argument to the provided URL.
+**Parameters**
+- **path** `string`: The URL path.
-### prependHTTP
+**Returns**
+
+`boolean`: True if the argument contains a valid path
+
+### isValidProtocol
+
+[src/index.js#L59-L64](src/index.js#L59-L64)
+
+Tests if a url protocol is valid.
+
+**Usage**
```js
-const actualURL = prependHTTP( 'wordpress.org' ); // http://wordpress.org
+const isValid = isValidProtocol( 'https:' ); // true
+const isNotValid = isValidProtocol( 'https :' ); // false
```
-Prepends the provided partial URL with the http:// protocol.
+**Parameters**
-### getQueryArg
+- **protocol** `string`: The url protocol.
+
+**Returns**
+
+`boolean`: True if the argument is a valid protocol (e.g. http\:, tel:).
+
+### isValidQueryString
+
+[src/index.js#L179-L184](src/index.js#L179-L184)
+
+Checks for invalid characters within the provided query string.
+
+**Usage**
```js
-const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar
+const isValid = isValidQueryString( 'query=true&another=false' ); // true
+const isNotValid = isValidQueryString( 'query=true?another=false' ); // false
```
-Retrieve a query string argument from the provided URL.
+**Parameters**
+- **queryString** `string`: The query string.
-### hasQueryArg
+**Returns**
+
+`boolean`: True if the argument contains a valid query string.
+
+### prependHTTP
+
+[src/index.js#L338-L344](src/index.js#L338-L344)
+
+Prepends "http\://" to a url, if it looks like something that is meant to be a TLD.
+
+**Usage**
```js
-const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true
+const actualURL = prependHTTP( 'wordpress.org' ); // http://wordpress.org
```
-Checks whether a URL contains the given query string argument.
+**Parameters**
+
+- **url** `string`: The URL to test
+
+**Returns**
+`string`: The updated URL
### removeQueryArgs
+[src/index.js#L316-L324](src/index.js#L316-L324)
+
+Removes arguments from the query string of the url
+
+**Usage**
+
```js
const newUrl = removeQueryArgs( 'https://wordpress.org?foo=bar&bar=baz&baz=foobar', 'foo', 'bar' ); // https://wordpress.org?baz=foobar
```
-Removes one or more query string arguments from the given URL.
+**Parameters**
+- **url** `string`: URL
+- **args** `...string`: Query Args
+
+**Returns**
+
+`string`: Updated URL
### safeDecodeURI
+[src/index.js#L359-L365](src/index.js#L359-L365)
+
+Safely decodes a URI with `decodeURI`. Returns the URI unmodified if
+`decodeURI` throws an error.
+
+**Usage**
+
```js
const badUri = safeDecodeURI( '%z' ); // does not throw an Error, simply returns '%z'
```
-Safely decodes a URI with `decodeURI`. Returns the URI unmodified if `decodeURI` throws an Error.
+**Parameters**
-### filterURLForDisplay
+- **uri** `string`: URI to decode.
+
+**Returns**
+
+`string`: Decoded URI if possible.
+
+### safeDecodeURIComponent
+
+[src/index.js#L399-L405](src/index.js#L399-L405)
+
+Safely decodes a URI component with `decodeURIComponent`. Returns the URI component unmodified if
+`decodeURIComponent` throws an error.
+
+**Parameters**
+
+- **uriComponent** `string`: URI component to decode.
+
+**Returns**
+
+`string`: Decoded URI component if possible.
-```js
-const displayUrl = filterURLForDisplay( 'https://www.wordpress.org/gutenberg/' ); // wordpress.org/gutenberg
-```
-Returns a URL for display, without protocol, www subdomain, or trailing slash.
+
diff --git a/packages/url/src/index.js b/packages/url/src/index.js
index d060f3539d76ed..c5037cdf417303 100644
--- a/packages/url/src/index.js
+++ b/packages/url/src/index.js
@@ -12,6 +12,11 @@ const USABLE_HREF_REGEXP = /^(?:[a-z]+:|#|\?|\.|\/)/i;
*
* @param {string} url The string to scrutinise.
*
+ * @example
+ * ```js
+ * const isURL = isURL( 'https://wordpress.org' ); // true
+ * ```
+ *
* @return {boolean} Whether or not it looks like a URL.
*/
export function isURL( url ) {
@@ -23,6 +28,12 @@ export function isURL( url ) {
*
* @param {string} url The full URL.
*
+ * @example
+ * ```js
+ * const protocol1 = getProtocol( 'tel:012345678' ); // 'tel:'
+ * const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:'
+ * ```
+ *
* @return {?string} The protocol part of the URL.
*/
export function getProtocol( url ) {
@@ -37,6 +48,12 @@ export function getProtocol( url ) {
*
* @param {string} protocol The url protocol.
*
+ * @example
+ * ```js
+ * const isValid = isValidProtocol( 'https:' ); // true
+ * const isNotValid = isValidProtocol( 'https :' ); // false
+ * ```
+ *
* @return {boolean} True if the argument is a valid protocol (e.g. http:, tel:).
*/
export function isValidProtocol( protocol ) {
@@ -51,6 +68,12 @@ export function isValidProtocol( protocol ) {
*
* @param {string} url The full URL.
*
+ * @example
+ * ```js
+ * const authority1 = getAuthority( 'https://wordpress.org/help/' ); // 'wordpress.org'
+ * const authority2 = getAuthority( 'https://localhost:8080/test/' ); // 'localhost:8080'
+ * ```
+ *
* @return {?string} The authority part of the URL.
*/
export function getAuthority( url ) {
@@ -65,6 +88,12 @@ export function getAuthority( url ) {
*
* @param {string} authority A string containing the URL authority.
*
+ * @example
+ * ```js
+ * const isValid = isValidAuthority( 'wordpress.org' ); // true
+ * const isNotValid = isValidAuthority( 'wordpress#org' ); // false
+ * ```
+ *
* @return {boolean} True if the argument contains a valid authority.
*/
export function isValidAuthority( authority ) {
@@ -79,6 +108,12 @@ export function isValidAuthority( authority ) {
*
* @param {string} url The full URL.
*
+ * @example
+ * ```js
+ * const path1 = getPath( 'http://localhost:8080/this/is/a/test?query=true' ); // 'this/is/a/test'
+ * const path2 = getPath( 'https://wordpress.org/help/faq/' ); // 'help/faq'
+ * ```
+ *
* @return {?string} The path part of the URL.
*/
export function getPath( url ) {
@@ -93,6 +128,12 @@ export function getPath( url ) {
*
* @param {string} path The URL path.
*
+ * @example
+ * ```js
+ * const isValid = isValidPath( 'test/path/' ); // true
+ * const isNotValid = isValidPath( '/invalid?test/path/' ); // false
+ * ```
+ *
* @return {boolean} True if the argument contains a valid path
*/
export function isValidPath( path ) {
@@ -107,6 +148,12 @@ export function isValidPath( path ) {
*
* @param {string} url The full URL.
*
+ * @example
+ * ```js
+ * const queryString1 = getQueryString( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // 'query=true'
+ * const queryString2 = getQueryString( 'https://wordpress.org#fragment?query=false&search=hello' ); // 'query=false&search=hello'
+ * ```
+ *
* @return {?string} The query string part of the URL.
*/
export function getQueryString( url ) {
@@ -121,6 +168,12 @@ export function getQueryString( url ) {
*
* @param {string} queryString The query string.
*
+ * @example
+ * ```js
+ * const isValid = isValidQueryString( 'query=true&another=false' ); // true
+ * const isNotValid = isValidQueryString( 'query=true?another=false' ); // false
+ * ```
+ *
* @return {boolean} True if the argument contains a valid query string.
*/
export function isValidQueryString( queryString ) {
@@ -135,6 +188,12 @@ export function isValidQueryString( queryString ) {
*
* @param {string} url The full URL
*
+ * @example
+ * ```js
+ * const fragment1 = getFragment( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // '#fragment'
+ * const fragment2 = getFragment( 'https://wordpress.org#another-fragment?query=true' ); // '#another-fragment'
+ * ```
+ *
* @return {?string} The fragment part of the URL.
*/
export function getFragment( url ) {
@@ -149,6 +208,12 @@ export function getFragment( url ) {
*
* @param {string} fragment The url fragment.
*
+ * @example
+ * ```js
+ * const isValid = isValidFragment( '#valid-fragment' ); // true
+ * const isNotValid = isValidFragment( '#invalid-#fragment' ); // false
+ * ```
+ *
* @return {boolean} True if the argument contains a valid fragment.
*/
export function isValidFragment( fragment ) {
@@ -167,6 +232,11 @@ export function isValidFragment( fragment ) {
* only the resulting querystring is returned.
* @param {Object} args Query arguments to apply to URL.
*
+ * @example
+ * ```js
+ * const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://google.com/?q=test
+ * ```
+ *
* @return {string} URL with arguments applied.
*/
export function addQueryArgs( url = '', args ) {
@@ -199,6 +269,11 @@ export function addQueryArgs( url = '', args ) {
* @param {string} url URL
* @param {string} arg Query arg name
*
+ * @example
+ * ```js
+ * const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar
+ * ```
+ *
* @return {Array|string} Query arg value.
*/
export function getQueryArg( url, arg ) {
@@ -214,6 +289,11 @@ export function getQueryArg( url, arg ) {
* @param {string} url URL
* @param {string} arg Query arg name
*
+ * @example
+ * ```js
+ * const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true
+ * ```
+ *
* @return {boolean} Whether or not the URL contains the query arg.
*/
export function hasQueryArg( url, arg ) {
@@ -226,6 +306,11 @@ export function hasQueryArg( url, arg ) {
* @param {string} url URL
* @param {...string} args Query Args
*
+ * @example
+ * ```js
+ * const newUrl = removeQueryArgs( 'https://wordpress.org?foo=bar&bar=baz&baz=foobar', 'foo', 'bar' ); // https://wordpress.org?baz=foobar
+ * ```
+ *
* @return {string} Updated URL
*/
export function removeQueryArgs( url, ...args ) {
@@ -243,6 +328,11 @@ export function removeQueryArgs( url, ...args ) {
*
* @param {string} url The URL to test
*
+ * @example
+ * ```js
+ * const actualURL = prependHTTP( 'wordpress.org' ); // http://wordpress.org
+ * ```
+ *
* @return {string} The updated URL
*/
export function prependHTTP( url ) {
@@ -259,6 +349,11 @@ export function prependHTTP( url ) {
*
* @param {string} uri URI to decode.
*
+ * @example
+ * ```js
+ * const badUri = safeDecodeURI( '%z' ); // does not throw an Error, simply returns '%z'
+ * ```
+ *
* @return {string} Decoded URI if possible.
*/
export function safeDecodeURI( uri ) {
@@ -274,6 +369,11 @@ export function safeDecodeURI( uri ) {
*
* @param {string} url Original URL.
*
+ * @example
+ * ```js
+ * const displayUrl = filterURLForDisplay( 'https://www.wordpress.org/gutenberg/' ); // wordpress.org/gutenberg
+ * ```
+ *
* @return {string} Displayed URL.
*/
export function filterURLForDisplay( url ) {