[v8.x] test: improve the test common documentation

test/common/README.md

@@ -13,16 +13,16 @@ The `common` module is used by tests for consistency across repeated
 tasks.
 
 ### allowGlobals(...whitelist)
-* `whitelist` [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) Array of Globals
-* return [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+* `whitelist` [<Array>] Array of Globals
+* return [<Array>]
 
 Takes `whitelist` and concats that with predefined `knownGlobals`.
 
 ### arrayStream
 A stream to push an array into a REPL
 
 ### busyLoop(time)
-* `time` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
+* `time` [<Number>]
 
 Blocks for `time` amount of time.
 
@@ -41,177 +41,185 @@ no unexpected rejections occur, because currently they result in silent
 failures.
 
 ### ddCommand(filename, kilobytes)
-* return [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+* return [<Object>]
 
 Platform normalizes the `dd` command
 
 ### enoughTestMem
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Check if there is more than 1gb of total memory.
 
-### expectsError(settings)
-* `settings` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+### expectsError([fn, ]settings[, exact])
+* `fn` [<Function>]
+* `settings` [<Object>]
   with the following optional properties:
-  * `code` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+  * `code` [<String>]
     expected error must have this value for its `code` property
-  * `type` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
+  * `type` [<Function>]
     expected error must be an instance of `type`
-  * `message` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
-    or [<RegExp>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
+  * `message` [<String>]
+    or [<RegExp>]
     if a string is provided for `message`, expected error must have it for its
     `message` property; if a regular expression is provided for `message`, the
     regular expression must match the `message` property of the expected error
+* `exact` [<Number>] default = 1
 
 * return function suitable for use as a validation function passed as the second
-  argument to `assert.throws()`
+  argument to e.g. `assert.throws()`. If the returned function has not been
+  called exactly `exact` number of times when the test is complete, then the
+  test will fail.
+
+If `fn` is provided, it will be passed to `assert.throws` as first argument.
 
 The expected error should be [subclassed by the `internal/errors` module](https://github.com/nodejs/node/blob/master/doc/guides/using-internal-errors.md#api).
 
 ### expectWarning(name, expected)
-* `name` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
-* `expected` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+* `name` [<String>]
+* `expected` [<String>] | [<Array>]
 
 Tests whether `name` and `expected` are part of a raised warning.
 
 ### fileExists(pathname)
-* pathname [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* pathname [<String>]
+* return [<Boolean>]
 
 Checks if `pathname` exists
 
 ### fixturesDir
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* return [<String>]
 
 Path to the 'fixtures' directory.
 
 ### getArrayBufferViews(buf)
-* `buf` [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer)
-* return [<ArrayBufferView[]>](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView)
+* `buf` [<Buffer>]
+* return [<ArrayBufferView[]>]
 
 Returns an instance of all possible `ArrayBufferView`s of the provided Buffer.
 
 ### globalCheck
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Turn this off if the test should not check for global leaks.
 
 ### hasCrypto
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Checks for 'openssl'.
 
 ### hasFipsCrypto
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Checks `hasCrypto` and `crypto` with fips.
 
 ### hasIntl
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Checks if [internationalization] is supported.
 
 ### hasSmallICU
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Checks `hasIntl` and `small-icu` is supported.
 
 ### hasIPv6
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Checks whether `IPv6` is supported on this platform.
 
 ### hasMultiLocalhost
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Checks if there are multiple localhosts available.
 
 ### hijackStderr(listener)
-* `listener` [<Function>][MDN-Function]: a listener with a single parameter called `data`.
+* `listener` [<Function>]: a listener with a single parameter
+  called `data`.
 
 Eavesdrop to `process.stderr.write` calls. Once `process.stderr.write` is
 called, `listener` will also be called and the `data` of `write` function will
 be passed to `listener`. What's more, `process.stderr.writeTimes` is a count of
 the number of calls.
 
 ### hijackStdout(listener)
-* `listener` [<Function>][MDN-Function]: a listener with a single parameter called `data`.
+* `listener` [<Function>]: a listener with a single parameter
+  called `data`.
 
 Eavesdrop to `process.stdout.write` calls. Once `process.stdout.write` is
 called, `listener` will also be called and the `data` of `write` function will
 be passed to `listener`. What's more, `process.stdout.writeTimes` is a count of
 the number of calls.
 
 ### inFreeBSDJail
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Checks whether free BSD Jail is true or false.
 
 ### isAIX
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Platform check for Advanced Interactive eXecutive (AIX).
 
 ### isAlive(pid)
-* `pid` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* `pid` [<Number>]
+* return [<Boolean>]
 
 Attempts to 'kill' `pid`
 
 ### isFreeBSD
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Platform check for Free BSD.
 
 ### isLinux
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Platform check for Linux.
 
 ### isLinuxPPCBE
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Platform check for Linux on PowerPC.
 
 ### isOSX
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Platform check for macOS.
 
 ### isSunOS
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Platform check for SunOS.
 
 ### isWindows
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Platform check for Windows.
 
 ### isWOW64
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Platform check for Windows 32-bit on Windows 64-bit.
 
 ### leakedGlobals
-* return [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+* return [<Array>]
 
 Checks whether any globals are not on the `knownGlobals` list.
 
 ### localhostIPv4
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* return [<String>]
 
 Gets IP of localhost
 
 ### localIPv6Hosts
-* return [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+* return [<Array>]
 
 Array of IPV6 hosts.
 
 ### mustCall([fn][, exact])
-* `fn` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) default = () => {}
-* `exact` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1
-* return [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
+* `fn` [<Function>] default = () => {}
+* `exact` [<Number>] default = 1
+* return [<Function>]
 
 Returns a function that calls `fn`. If the returned function has not been called
 exactly `expected` number of times when the test is complete, then the test will
@@ -220,9 +228,9 @@ fail.
 If `fn` is not provided, an empty function will be used.
 
 ### mustCallAtLeast([fn][, minimum])
-* `fn` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) default = () => {}
-* `minimum` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = 1
-* return [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
+* `fn` [<Function>] default = () => {}
+* `minimum` [<Number>] default = 1
+* return [<Function>]
 
 Returns a function that calls `fn`. If the returned function has not been called
 at least `minimum` number of times when the test is complete, then the test will
@@ -231,46 +239,49 @@ fail.
 If `fn` is not provided, an empty function will be used.
 
 ### mustNotCall([msg])
-* `msg` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) default = 'function should not have been called'
-* return [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
+* `msg` [<String>] default = 'function should not have been called'
+* return [<Function>]
 
-Returns a function that triggers an `AssertionError` if it is invoked. `msg` is used as the error message for the `AssertionError`.
+Returns a function that triggers an `AssertionError` if it is invoked. `msg` is
+used as the error message for the `AssertionError`.
 
 ### nodeProcessAborted(exitCode, signal)
-* `exitCode` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
-* `signal` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* `exitCode` [<Number>]
+* `signal` [<String>]
+* return [<Boolean>]
 
-Returns `true` if the exit code `exitCode` and/or signal name `signal` represent the exit code and/or signal name of a node process that aborted, `false` otherwise.
+Returns `true` if the exit code `exitCode` and/or signal name `signal` represent
+the exit code and/or signal name of a node process that aborted, `false`
+otherwise.
 
 ### opensslCli
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* return [<Boolean>]
 
 Checks whether 'opensslCli' is supported.
 
 ### platformTimeout(ms)
-* `ms` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
-* return [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
+* `ms` [<Number>]
+* return [<Number>]
 
 Platform normalizes timeout.
 
 ### PIPE
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* return [<String>]
 
 Path to the test sock.
 
 ### PORT
-* return [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = `12346`
+* return [<Number>] default = `12346`
 
 Port tests are running on.
 
 ### printSkipMessage(msg)
-* `msg` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* `msg` [<String>]
 
 Logs '1..0 # Skipped: ' + `msg`
 
 ### refreshTmpDir
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* return [<String>]
 
 Deletes the 'tmp' dir and recreates it
 
@@ -283,34 +294,34 @@ Restore the original `process.stderr.write`.
 Restore the original `process.stdout.write`.
 
 ### rootDir
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* return [<String>]
 
 Path to the 'root' directory. either `/` or `c:\\` (windows)
 
 ### skip(msg)
-* `msg` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* `msg` [<String>]
 
 Logs '1..0 # Skipped: ' + `msg` and exits with exit code `0`.
 
 ### spawnPwd(options)
-* `options` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
-* return [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+* `options` [<Object>]
+* return [<Object>]
 
 Platform normalizes the `pwd` command.
 
 ### spawnSyncPwd(options)
-* `options` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
-* return [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+* `options` [<Object>]
+* return [<Object>]
 
 Synchronous version of `spawnPwd`.
 
 ### tmpDir
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* return [<String>]
 
 The realpath of the 'tmp' directory.
 
 ### tmpDirName
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* return [<String>]
 
 Name of the temp directory used by tests.
 
@@ -323,5 +334,13 @@ Node.js
 implementation with tests from
 [W3C Web Platform Tests](https://github.com/w3c/web-platform-tests).
 
-[MDN-Function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Normal_objects_and_functions
+[<Array>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
+[<ArrayBufferView[]>]: https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView
+[<Boolean>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type
+[<Buffer>]: https://nodejs.org/api/buffer.html#buffer_class_buffer
+[<Function>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
+[<Number>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
+[<Object>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
+[<RegExp>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
+[<String>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
 [internationalization]: https://github.com/nodejs/node/wiki/Intl