test,doc: do not indicate that non-functions "return" values

Update documentation for test `common` module so that properties that
are not functions do not specify a return type and functions that do
return values specify the type.

PR-URL: #17267
Reviewed-By: Vse Mozhet Byt <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Gibson Fahnestock <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>

Author: Trott

test/common/README.md

@@ -26,12 +26,14 @@ A stream to push an array into a REPL
 
 Blocks for `time` amount of time.
 
-### canCreateSymLink
-API to indicate whether the current running process can create
-symlinks. On Windows, this returns false if the process running
-doesn't have privileges to create symlinks (specifically
-[SeCreateSymbolicLinkPrivilege](https://msdn.microsoft.com/en-us/library/windows/desktop/bb530716(v=vs.85).aspx)).
-On non-Windows platforms, this currently returns true.
+### canCreateSymLink()
+* return [<Boolean>]
+
+Checks whether the current running process can create symlinks. On Windows, this
+returns `false` if the process running doesn't have privileges to create
+symlinks
+([SeCreateSymbolicLinkPrivilege](https://msdn.microsoft.com/en-us/library/windows/desktop/bb530716(v=vs.85).aspx)).
+On non-Windows platforms, this always returns `true`.
 
 ### crashOnUnhandledRejection()
 
@@ -46,9 +48,9 @@ failures.
 Platform normalizes the `dd` command
 
 ### enoughTestMem
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
-Check if there is more than 1gb of total memory.
+Indicates 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)
@@ -81,7 +83,7 @@ Tests whether `name` and `expected` are part of a raised warning.
 Checks if `pathname` exists
 
 ### fixturesDir
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
 
 Path to the 'fixtures' directory.
 
@@ -92,37 +94,37 @@ Path to the 'fixtures' directory.
 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)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
-Turn this off if the test should not check for global leaks.
+Set to `false` 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)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
-Checks for 'openssl'.
+Indicates whether OpenSSL is available.
 
 ### hasFipsCrypto
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
-Checks `hasCrypto` and `crypto` with fips.
+Indicates `hasCrypto` and `crypto` with fips.
 
 ### hasIPv6
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
-Checks whether `IPv6` is supported on this platform.
+Indicates whether `IPv6` is supported on this platform.
 
 ### hasMultiLocalhost
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
-Checks if there are multiple localhosts available.
+Indicates if there are multiple localhosts available.
 
 ### inFreeBSDJail
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 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)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 Platform check for Advanced Interactive eXecutive (AIX).
 
@@ -133,54 +135,54 @@ Platform check for Advanced Interactive eXecutive (AIX).
 Attempts to 'kill' `pid`
 
 ### isFreeBSD
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 Platform check for Free BSD.
 
 ### isLinux
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 Platform check for Linux.
 
 ### isLinuxPPCBE
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 Platform check for Linux on PowerPC.
 
 ### isOSX
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 Platform check for macOS.
 
 ### isSunOS
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 Platform check for SunOS.
 
 ### isWindows
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 Platform check for Windows.
 
 ### isWOW64
-* return [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
 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)
+* [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
 
-Checks whether any globals are not on the `knownGlobals` list.
+Indicates 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)
+* [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
 
-Gets IP of localhost
+IP of `localhost`.
 
 ### localIPv6Hosts
-* return [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
+* [<Array>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
 
-Array of IPV6 hosts.
+Array of IPV6 representations for `localhost`.
 
 ### mustCall([fn][, exact])
 * `fn` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) default = () => {}
@@ -218,9 +220,9 @@ Returns a function that triggers an `AssertionError` if it is invoked. `msg` is
 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)
+* [<Boolean>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)
 
-Checks whether 'opensslCli' is supported.
+Indicates whether 'opensslCli' is supported.
 
 ### platformTimeout(ms)
 * `ms` [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)
@@ -229,14 +231,14 @@ Checks whether 'opensslCli' is supported.
 Platform normalizes timeout.
 
 ### PIPE
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
 
-Path to the test sock.
+Path to the test socket.
 
 ### PORT
-* return [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = `12346`
+* [<Number>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) default = `12346`
 
-Port tests are running on.
+A port number for tests to use if one is needed.
 
 ### printSkipMessage(msg)
 * `msg` [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
@@ -249,7 +251,7 @@ Logs '1..0 # Skipped: ' + `msg`
 Deletes the 'tmp' dir and recreates it
 
 ### rootDir
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
 
 Path to the 'root' directory. either `/` or `c:\\` (windows)
 
@@ -271,7 +273,7 @@ Platform normalizes the `pwd` command.
 Synchronous version of `spawnPwd`.
 
 ### tmpDir
-* return [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
+* [<String>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)
 
 The realpath of the 'tmp' directory.