Port documentation to JSDoc for joinUrl (#957)

docs(joinUrl): port documentation to JSDoc

Also make the array of arguments `readonly`, which ensures
no mutation of the input is permitted inside the function body.

Slightly reword the documentation.

.changeset/young-penguins-invent.md

@@ -0,0 +1,5 @@
+---
+'@guardian/libs': patch
+---
+
+`joinUrl`: better documentation using JSDoc

libs/@guardian/libs/src/joinUrl/README.md

@@ -11,6 +11,6 @@ Handles trailing or leading spaces and double slashes.
 ```js
 import { joinUrl } from '@guardian/libs';
 
-const url = joinUrl('http://example.com/ ', ' /abc/', '/xyz/');
-// 'http://example.com/abc/xyz'
+const url = joinUrl('https://example.com/', '/media', '/', '//source.png');
+console.assert(url === 'https://example.com/media/source.png');
 ```

libs/@guardian/libs/src/joinUrl/joinUrl.ts

@@ -1,5 +1,21 @@
-// detect two or more `/` chars after a word boundary
+/** detect two or more `/` chars after a word boundary */
 const multipleSlashesInRoute = /\b\/{2,}/g;
 
-export const joinUrl = (...args: string[]): string =>
+/**
+ * Takes a variable number of strings as arguments,
+ * joining them as a single valid URL string.
+ *
+ * Handles trailing or leading spaces and double slashes.
+ *
+ * @returns a normalised URL pathname
+ *
+ * @example
+ * ```js
+ * import { joinUrl } from '@guardian/libs';
+ *
+ * const url = joinUrl('https://example.com/', '/media', '/', '//source.png');
+ * console.assert(url === 'https://example.com/media/source.png');
+ * ```
+ */
+export const joinUrl = (...args: readonly string[]): string =>
 	args.join('/').replace(multipleSlashesInRoute, '/');