From dd629efcd531142ef08406c9beff0daba3049dd4 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 22 Nov 2017 14:12:11 -0800 Subject: [PATCH] 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: https://github.com/nodejs/node/pull/17267 Reviewed-By: Vse Mozhet Byt Reviewed-By: Luigi Pinca Reviewed-By: Gibson Fahnestock Reviewed-By: Colin Ihrig --- test/common/README.md | 97 ++++++++++++++++++++++--------------------- 1 file changed, 49 insertions(+), 48 deletions(-) diff --git a/test/common/README.md b/test/common/README.md index e6371265d8b971..30dd9a2f04d46b 100644 --- a/test/common/README.md +++ b/test/common/README.md @@ -43,12 +43,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() @@ -63,9 +65,9 @@ failures. Platform normalizes the `dd` command ### enoughTestMem -* return [<Boolean>] +* [<Boolean>] -Check if there is more than 1gb of total memory. +Indicates if there is more than 1gb of total memory. ### expectsError([fn, ]settings[, exact]) * `fn` [<Function>] a function that should throw. @@ -126,7 +128,7 @@ that happens within the `timeoutMs` timespan, or rejects with `error` as a reason otherwise. ### fixturesDir -* return [<String>] +* [<String>] Path to the 'fixtures' directory. @@ -137,39 +139,39 @@ Path to the 'fixtures' directory. Returns an instance of all possible `ArrayBufferView`s of the provided Buffer. ### globalCheck -* return [<Boolean>] +* [<Boolean>] -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>] +* [<Boolean>] -Checks for 'openssl'. +Indicates whether OpenSSL is available. ### hasFipsCrypto -* return [<Boolean>] +* [<Boolean>] -Checks `hasCrypto` and `crypto` with fips. +Indicates `hasCrypto` and `crypto` with fips. ### hasIntl -* return [<Boolean>] +* [<Boolean>] -Checks if [internationalization] is supported. +Indicates if [internationalization] is supported. ### hasSmallICU -* return [<Boolean>] +* [<Boolean>] -Checks `hasIntl` and `small-icu` is supported. +Indicates `hasIntl` and `small-icu` are supported. ### hasIPv6 -* return [<Boolean>] +* [<Boolean>] -Checks whether `IPv6` is supported on this platform. +Indicates whether `IPv6` is supported on this platform. ### hasMultiLocalhost -* return [<Boolean>] +* [<Boolean>] -Checks if there are multiple localhosts available. +Indicates if there are multiple localhosts available. ### hijackStderr(listener) * `listener` [<Function>]: a listener with a single parameter @@ -190,12 +192,12 @@ be passed to `listener`. What's more, `process.stdout.writeTimes` is a count of the number of calls. ### inFreeBSDJail -* return [<Boolean>] +* [<Boolean>] Checks whether free BSD Jail is true or false. ### isAIX -* return [<Boolean>] +* [<Boolean>] Platform check for Advanced Interactive eXecutive (AIX). @@ -206,54 +208,54 @@ Platform check for Advanced Interactive eXecutive (AIX). Attempts to 'kill' `pid` ### isFreeBSD -* return [<Boolean>] +* [<Boolean>] Platform check for Free BSD. ### isLinux -* return [<Boolean>] +* [<Boolean>] Platform check for Linux. ### isLinuxPPCBE -* return [<Boolean>] +* [<Boolean>] Platform check for Linux on PowerPC. ### isOSX -* return [<Boolean>] +* [<Boolean>] Platform check for macOS. ### isSunOS -* return [<Boolean>] +* [<Boolean>] Platform check for SunOS. ### isWindows -* return [<Boolean>] +* [<Boolean>] Platform check for Windows. ### isWOW64 -* return [<Boolean>] +* [<Boolean>] Platform check for Windows 32-bit on Windows 64-bit. -### leakedGlobals +### leakedGlobals() * return [<Array>] -Checks whether any globals are not on the `knownGlobals` list. +Indicates whether any globals are not on the `knownGlobals` list. ### localhostIPv4 -* return [<String>] +* [<String>] -Gets IP of localhost +IP of `localhost`. ### localIPv6Hosts -* return [<Array>] +* [<Array>] -Array of IPV6 hosts. +Array of IPV6 representations for `localhost`. ### mustCall([fn][, exact]) * `fn` [<Function>] default = () => {} @@ -294,9 +296,9 @@ the exit code and/or signal name of a node process that aborted, `false` otherwise. ### opensslCli -* return [<Boolean>] +* [<Boolean>] -Checks whether 'opensslCli' is supported. +Indicates whether 'opensslCli' is supported. ### platformTimeout(ms) * `ms` [<Number>] @@ -305,14 +307,14 @@ Checks whether 'opensslCli' is supported. Platform normalizes timeout. ### PIPE -* return [<String>] +* [<String>] -Path to the test sock. +Path to the test socket. ### PORT -* return [<Number>] default = `12346` +* [<Number>] -Port tests are running on. +A port number for tests to use if one is needed. ### printSkipMessage(msg) * `msg` [<String>] @@ -335,12 +337,12 @@ Restore the original `process.stdout.write`. Used to restore `stdout` to its original state after calling [`common.hijackStdOut()`][]. ### rootDir -* return [<String>] +* [<String>] Path to the 'root' directory. either `/` or `c:\\` (windows) ### projectDir -* return [<String>] +* [<String>] Path to the project directory. @@ -372,7 +374,7 @@ Platform normalizes the `pwd` command. Synchronous version of `spawnPwd`. ### tmpDir -* return [<String>] +* [<String>] The realpath of the 'tmp' directory. @@ -422,7 +424,6 @@ The `DNS` module provides utilities related to the `dns` built-in module. * `syscall` [<String>] Defaults to `dns.mockedSysCall`. * return [<Function>] - A mock for the `lookup` option of `net.connect()` that would result in an error with the `code` and the `syscall` specified. Returns a function that has the same signature as `dns.lookup()`.