From 4f6dd9649fa31e31bbb81a7b07f692ee7a1013bf 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 | 86 ++++++++++++++++++++++--------------------- 1 file changed, 44 insertions(+), 42 deletions(-) diff --git a/test/common/README.md b/test/common/README.md index defe9c1a38a989..9ea825694f5ad2 100644 --- a/test/common/README.md +++ b/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.