diff options
| -rw-r--r-- | CPP_STYLE_GUIDE.md | 8 | ||||
| -rw-r--r-- | benchmark/README.md | 2 | ||||
| -rw-r--r-- | test/common/README.md | 266 | ||||
| -rw-r--r-- | tools/icu/README.md | 12 |
4 files changed, 145 insertions, 143 deletions
diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index 30a2ec99fa..8808405b2c 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -206,8 +206,8 @@ Use explicit comparisons to `nullptr` when testing pointers, i.e. ### Ownership and Smart Pointers -* [R.20]: Use `std::unique_ptr` or `std::shared_ptr` to represent ownership -* [R.21]: Prefer `unique_ptr` over `shared_ptr` unless you need to share +* [R.20][]: Use `std::unique_ptr` or `std::shared_ptr` to represent ownership +* [R.21][]: Prefer `unique_ptr` over `shared_ptr` unless you need to share ownership Use `std::unique_ptr` to make ownership transfer explicit. For example: @@ -286,8 +286,8 @@ data[0] = 12345; Further reading: -* [ES.48]: Avoid casts -* [ES.49]: If you must use a cast, use a named cast +* [ES.48][]: Avoid casts +* [ES.49][]: If you must use a cast, use a named cast ### Using `auto` diff --git a/benchmark/README.md b/benchmark/README.md index 1e82614dbb..45256670fd 100644 --- a/benchmark/README.md +++ b/benchmark/README.md @@ -74,7 +74,7 @@ The common.js module is used by benchmarks for consistency across repeated tasks. It has a number of helpful functions and properties to help with writing benchmarks. -### createBenchmark(fn, configs[, options]) +### createBenchmark(fn, configs\[, options\]) See [the guide on writing benchmarks](../doc/guides/writing-and-running-benchmarks.md#basics-of-a-benchmark). diff --git a/test/common/README.md b/test/common/README.md index 415f05a867..db32c48b40 100644 --- a/test/common/README.md +++ b/test/common/README.md @@ -29,10 +29,10 @@ The `benchmark` module is used by tests to run benchmarks. ### runBenchmark(name, args, env) -* `name` [<string>] Name of benchmark suite to be run. -* `args` [<Array>] Array of environment variable key/value pairs (ex: +* `name` [<string>][] Name of benchmark suite to be run. +* `args` [<Array>][] Array of environment variable key/value pairs (ex: `n=1`) to be applied via `--set`. -* `env` [<Object>] Environment variables to be applied during the run. +* `env` [<Object>][] Environment variables to be applied during the run. ## Common Module API @@ -40,18 +40,18 @@ The `common` module is used by tests for consistency across repeated tasks. ### allowGlobals(...whitelist) -* `whitelist` [<Array>] Array of Globals -* return [<Array>] +* `whitelist` [<Array>][] Array of Globals +* return [<Array>][] Takes `whitelist` and concats that with predefined `knownGlobals`. ### busyLoop(time) -* `time` [<number>] +* `time` [<number>][] Blocks for `time` amount of time. ### canCreateSymLink() -* return [<boolean>] +* 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 @@ -72,28 +72,28 @@ failures. However, it is useful in some rare cases to disable it, for example if the `unhandledRejection` hook is directly used by the test. ### enoughTestMem -* [<boolean>] +* [<boolean>][] Indicates if there is more than 1gb of total memory. -### expectsError([fn, ]settings[, exact]) -* `fn` [<Function>] a function that should throw. -* `settings` [<Object>] +### expectsError(\[fn, \]settings\[, exact\]) +* `fn` [<Function>][] a function that should throw. +* `settings` [<Object>][] that must contain the `code` property plus any of the other following properties (some properties only apply for `AssertionError`): - * `code` [<string>] + * `code` [<string>][] expected error must have this value for its `code` property. - * `type` [<Function>] + * `type` [<Function>][] expected error must be an instance of `type` and must be an Error subclass. - * `message` [<string>] or [<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. - * `name` [<string>] + * `name` [<string>][] expected error must have this value for its `name` property. * `info` <Object> expected error must have the same `info` property that is deeply equal to this value. - * `generatedMessage` [<string>] + * `generatedMessage` [<string>][] (`AssertionError` only) expected error must have this value for its `generatedMessage` property. * `actual` <any> @@ -105,8 +105,8 @@ Indicates if there is more than 1gb of total memory. * `operator` <any> (`AssertionError` only) expected error must have this value for its `operator` property. -* `exact` [<number>] default = 1 -* return [<Function>] +* `exact` [<number>][] default = 1 +* return [<Function>][] If `fn` is provided, it will be passed to `assert.throws` as first argument and `undefined` will be returned. @@ -115,10 +115,10 @@ Indicates if there is more than 1gb of total memory. returned function has not been called exactly `exact` number of times when the test is complete, then the test will fail. -### expectWarning(name[, expected[, code]]) -* `name` [<string>] | [<Object>] -* `expected` [<string>] | [<Array>] | [<Object>] -* `code` [<string>] +### expectWarning(name\[, expected\[, code\]\]) +* `name` [<string>][] | [<Object>][] +* `expected` [<string>][] | [<Array>][] | [<Object>][] +* `code` [<string>][] Tests whether `name`, `expected`, and `code` are part of a raised warning. @@ -162,21 +162,21 @@ expectWarning({ ``` ### getArrayBufferViews(buf) -* `buf` [<Buffer>] -* return [<ArrayBufferView[]>] +* `buf` [<Buffer>][] +* return [<ArrayBufferView>][]\[\] Returns an instance of all possible `ArrayBufferView`s of the provided Buffer. ### getBufferSources(buf) -* `buf` [<Buffer>] -* return [<BufferSource[]>] +* `buf` [<Buffer>][] +* return [<BufferSource>][]\[\] Returns an instance of all possible `BufferSource`s of the provided Buffer, consisting of all `ArrayBufferView` and an `ArrayBuffer`. ### getCallSite(func) -* `func` [<Function>] -* return [<string>] +* `func` [<Function>][] +* return [<string>][] Returns the file name and line number for the provided Function. @@ -187,12 +187,12 @@ Attempts to get a valid TTY file descriptor. Returns `-1` if it fails. The TTY file descriptor is assumed to be capable of being writable. ### hasCrypto -* [<boolean>] +* [<boolean>][] Indicates whether OpenSSL is available. ### hasFipsCrypto -* [<boolean>] +* [<boolean>][] Indicates that Node.js has been linked with a FIPS compatible OpenSSL library, and that FIPS as been enabled using `--enable-fips`. @@ -202,80 +202,80 @@ been enabled or not, then `process.config.variables.openssl_is_fips` can be used to determine that situation. ### hasIntl -* [<boolean>] +* [<boolean>][] -Indicates if [internationalization] is supported. +Indicates if [internationalization][] is supported. ### hasIPv6 -* [<boolean>] +* [<boolean>][] Indicates whether `IPv6` is supported on this platform. ### hasMultiLocalhost -* [<boolean>] +* [<boolean>][] Indicates if there are multiple localhosts available. ### inFreeBSDJail -* [<boolean>] +* [<boolean>][] Checks whether free BSD Jail is true or false. ### isAIX -* [<boolean>] +* [<boolean>][] Platform check for Advanced Interactive eXecutive (AIX). ### isAlive(pid) -* `pid` [<number>] -* return [<boolean>] +* `pid` [<number>][] +* return [<boolean>][] Attempts to 'kill' `pid` ### isFreeBSD -* [<boolean>] +* [<boolean>][] Platform check for Free BSD. ### isLinux -* [<boolean>] +* [<boolean>][] Platform check for Linux. ### isLinuxPPCBE -* [<boolean>] +* [<boolean>][] Platform check for Linux on PowerPC. ### isOSX -* [<boolean>] +* [<boolean>][] Platform check for macOS. ### isSunOS -* [<boolean>] +* [<boolean>][] Platform check for SunOS. ### isWindows -* [<boolean>] +* [<boolean>][] Platform check for Windows. ### localhostIPv4 -* [<string>] +* [<string>][] IP of `localhost`. ### localIPv6Hosts -* [<Array>] +* [<Array>][] Array of IPV6 representations for `localhost`. -### mustCall([fn][, exact]) -* `fn` [<Function>] default = () => {} -* `exact` [<number>] default = 1 -* return [<Function>] +### mustCall(\[fn\]\[, exact\]) +* `fn` [<Function>][] default = () => {} +* `exact` [<number>][] default = 1 +* return [<Function>][] Returns a function that calls `fn`. If the returned function has not been called exactly `exact` number of times when the test is complete, then the test will @@ -283,10 +283,10 @@ fail. If `fn` is not provided, an empty function will be used. -### mustCallAtLeast([fn][, minimum]) -* `fn` [<Function>] default = () => {} -* `minimum` [<number>] default = 1 -* return [<Function>] +### mustCallAtLeast(\[fn\]\[, minimum\]) +* `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 @@ -294,52 +294,52 @@ fail. If `fn` is not provided, an empty function will be used. -### mustNotCall([msg]) -* `msg` [<string>] default = 'function should not have been called' -* return [<Function>] +### mustNotCall(\[msg\]) +* `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`. ### nodeProcessAborted(exitCode, signal) -* `exitCode` [<number>] -* `signal` [<string>] -* return [<boolean>] +* `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. ### opensslCli -* [<boolean>] +* [<boolean>][] Indicates whether 'opensslCli' is supported. ### platformTimeout(ms) -* `ms` [<number>] | [<bigint>] -* return [<number>] | [<bigint>] +* `ms` [<number>][] | [<bigint>][] +* return [<number>][] | [<bigint>][] Returns a timeout value based on detected conditions. For example, a debug build may need extra time so the returned value will be larger than on a release build. ### PIPE -* [<string>] +* [<string>][] Path to the test socket. ### PORT -* [<number>] +* [<number>][] A port number for tests to use if one is needed. ### printSkipMessage(msg) -* `msg` [<string>] +* `msg` [<string>][] Logs '1..0 # Skipped: ' + `msg` ### pwdCommand -* [<array>] First two argument for the `spawn`/`exec` functions. +* [<array>][] First two argument for the `spawn`/`exec` functions. Platform normalized `pwd` command options. Usage example: ```js @@ -350,12 +350,12 @@ spawn(...common.pwdCommand, { stdio: ['pipe'] }); ``` ### rootDir -* [<string>] +* [<string>][] Path to the 'root' directory. either `/` or `c:\\` (windows) ### runWithInvalidFD(func) -* `func` [<Function>] +* `func` [<Function>][] Runs `func` with an invalid file descriptor that is an unsigned integer and can be used to trigger `EBADF` as the first argument. If no such file @@ -363,7 +363,7 @@ descriptor could be generated, a skip message will be printed and the `func` will not be run. ### skip(msg) -* `msg` [<string>] +* `msg` [<string>][] Logs '1..0 # Skipped: ' + `msg` and exits with exit code `0`. @@ -450,7 +450,7 @@ Environment variables used in profiled processes. ### getCpuProfiles(dir) * `dir` {string} The directory containing the CPU profile files. -* return [<string>] +* return [<string>][] Returns an array of all `.cpuprofile` files found in `dir`. @@ -458,7 +458,7 @@ Returns an array of all `.cpuprofile` files found in `dir`. * `file` {string} Path to a `.cpuprofile` file. * `suffix` {string} Suffix of the URL of call frames to retrieve. -* returns { frames: [<Object>], nodes: [<Object>] } +* returns { frames: [<Object>][], nodes: [<Object>][] } Returns an object containing an array of the relevant call frames and an array of all the profile nodes. @@ -482,9 +482,9 @@ The `DNS` module provides utilities related to the `dns` built-in module. ### errorLookupMock(code, syscall) -* `code` [<string>] Defaults to `dns.mockedErrorCode`. -* `syscall` [<string>] Defaults to `dns.mockedSysCall`. -* return [<Function>] +* `code` [<string>][] Defaults to `dns.mockedErrorCode`. +* `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 @@ -500,39 +500,39 @@ The default `syscall` of errors generated by `errorLookupMock`. ### readDomainFromPacket(buffer, offset) -* `buffer` [<Buffer>] -* `offset` [<number>] -* return [<Object>] +* `buffer` [<Buffer>][] +* `offset` [<number>][] +* return [<Object>][] Reads the domain string from a packet and returns an object containing the number of bytes read and the domain. ### parseDNSPacket(buffer) -* `buffer` [<Buffer>] -* return [<Object>] +* `buffer` [<Buffer>][] +* return [<Object>][] Parses a DNS packet. Returns an object with the values of the various flags of the packet depending on the type of packet. ### writeIPv6(ip) -* `ip` [<string>] -* return [<Buffer>] +* `ip` [<string>][] +* return [<Buffer>][] Reads an IPv6 String and returns a Buffer containing the parts. ### writeDomainName(domain) -* `domain` [<string>] -* return [<Buffer>] +* `domain` [<string>][] +* return [<Buffer>][] Reads a Domain String and returns a Buffer containing the domain. ### writeDNSPacket(parsed) -* `parsed` [<Object>] -* return [<Buffer>] +* `parsed` [<Object>][] +* return [<Buffer>][] Takes in a parsed Object and writes its fields to a DNS packet as a Buffer object. @@ -572,26 +572,26 @@ files in the `test/fixtures` directory. ### fixtures.fixturesDir -* [<string>] +* [<string>][] The absolute path to the `test/fixtures/` directory. ### fixtures.path(...args) -* `...args` [<string>] +* `...args` [<string>][] Returns the result of `path.join(fixtures.fixturesDir, ...args)`. -### fixtures.readSync(args[, enc]) +### fixtures.readSync(args\[, enc\]) -* `args` [<string>] | [<Array>] +* `args` [<string>][] | [<Array>][] Returns the result of `fs.readFileSync(path.join(fixtures.fixturesDir, ...args), 'enc')`. -### fixtures.readKey(arg[, enc]) +### fixtures.readKey(arg\[, enc\]) -* `arg` [<string>] +* `arg` [<string>][] Returns the result of `fs.readFileSync(path.join(fixtures.fixturesDir, 'keys', arg), 'enc')`. @@ -610,11 +610,11 @@ one listed below. (`heap.validateSnapshotNodes(...)` is a shortcut for ### heap.validateSnapshotNodes(name, expected, options) -* `name` [<string>] Look for this string as the name of heap dump nodes. -* `expected` [<Array>] A list of objects, possibly with an `children` +* `name` [<string>][] Look for this string as the name of heap dump nodes. +* `expected` [<Array>][] A list of objects, possibly with an `children` property that points to expected other adjacent nodes. -* `options` [<Array>] - * `loose` [<boolean>] Do not expect an exact listing of occurrences +* `options` [<Array>][] + * `loose` [<boolean>][] Do not expect an exact listing of occurrences of nodes with name `name` in `expected`. Create a heap dump and an embedder graph copy and validate occurrences. @@ -650,7 +650,7 @@ console.log('this is sent to the hijacked listener'); ``` ### hijackStderr(listener) -* `listener` [<Function>]: a listener with a single parameter +* `listener` [<Function>][]: a listener with a single parameter called `data`. Eavesdrop to `process.stderr.write()` calls. Once `process.stderr.write()` is @@ -659,7 +659,7 @@ be passed to `listener`. What's more, `process.stderr.writeTimes` is a count of the number of calls. ### hijackStdout(listener) -* `listener` [<Function>]: a listener with a single parameter +* `listener` [<Function>][]: a listener with a single parameter called `data`. Eavesdrop to `process.stdout.write()` calls. Once `process.stdout.write()` is @@ -795,27 +795,27 @@ internet-related tests. ### internet.addresses -* [<Object>] - * `INET_HOST` [<string>] A generic host that has registered common +* [<Object>][] + * `INET_HOST` [<string>][] A generic host that has registered common DNS records, supports both IPv4 and IPv6, and provides basic HTTP/HTTPS services - * `INET4_HOST` [<string>] A host that provides IPv4 services - * `INET6_HOST` [<string>] A host that provides IPv6 services - * `INET4_IP` [<string>] An accessible IPv4 IP, defaults to the + * `INET4_HOST` [<string>][] A host that provides IPv4 services + * `INET6_HOST` [<string>][] A host that provides IPv6 services + * `INET4_IP` [<string>][] An accessible IPv4 IP, defaults to the Google Public DNS IPv4 address - * `INET6_IP` [<string>] An accessible IPv6 IP, defaults to the + * `INET6_IP` [<string>][] An accessible IPv6 IP, defaults to the Google Public DNS IPv6 address - * `INVALID_HOST` [<string>] An invalid host that cannot be resolved - * `MX_HOST` [<string>] A host with MX records registered - * `SRV_HOST` [<string>] A host with SRV records registered - * `PTR_HOST` [<string>] A host with PTR records registered - * `NAPTR_HOST` [<string>] A host with NAPTR records registered - * `SOA_HOST` [<string>] A host with SOA records registered - * `CNAME_HOST` [<string>] A host with CNAME records registered - * `NS_HOST` [<string>] A host with NS records registered - * `TXT_HOST` [<string>] A host with TXT records registered - * `DNS4_SERVER` [<string>] An accessible IPv4 DNS server - * `DNS6_SERVER` [<string>] An accessible IPv6 DNS server + * `INVALID_HOST` [<string>][] An invalid host that cannot be resolved + * `MX_HOST` [<string>][] A host with MX records registered + * `SRV_HOST` [<string>][] A host with SRV records registered + * `PTR_HOST` [<string>][] A host with PTR records registered + * `NAPTR_HOST` [<string>][] A host with NAPTR records registered + * `SOA_HOST` [<string>][] A host with SOA records registered + * `CNAME_HOST` [<string>][] A host with CNAME records registered + * `NS_HOST` [<string>][] A host with NS records registered + * `TXT_HOST` [<string>][] A host with TXT records registered + * `DNS4_SERVER` [<string>][] An accessible IPv4 DNS server + * `DNS6_SERVER` [<string>][] An accessible IPv6 DNS server A set of addresses for internet-related tests. All properties are configurable via `NODE_TEST_*` environment variables. For example, to configure @@ -835,9 +835,9 @@ onGC({}, { ongc() { console.log('collected'); } }); ``` ### onGC(target, listener) -* `target` [<Object>] -* `listener` [<Object>] - * `ongc` [<Function>] +* `target` [<Object>][] +* `listener` [<Object>][] + * `ongc` [<Function>][] Installs a GC listener for the collection of `target`. @@ -856,24 +856,25 @@ functionality. ### findReports(pid, dir) -* `pid` [<number>] Process ID to retrieve diagnostic report files for. -* `dir` [<string>] Directory to search for diagnostic report files. -* return [<Array>] +* `pid` [<number>][] Process ID to retrieve diagnostic report files for. +* `dir` [<string>][] Directory to search for diagnostic report files. +* return [<Array>][] Returns an array of diagnotic report file names found in `dir`. The files should have been generated by a process whose PID matches `pid`. ### validate(filepath) -* `filepath` [<string>] Diagnostic report filepath to validate. +* `filepath` [<string>][] Diagnostic report filepath to validate. Validates the schema of a diagnostic report file whose path is specified in `filepath`. If the report fails validation, an exception is thrown. ### validateContent(report) -* `report` [<Object|string>] JSON contents of a diagnostic report file, the -parsed Object thereof, or the result of `process.report.getReport()`. +* `report` [<Object>][] | [<string>][] JSON contents of a diagnostic + report file, the parsed Object thereof, or the result of + `process.report.getReport()`. Validates the schema of a diagnostic report whose content is specified in `report`. If the report fails validation, an exception is thrown. @@ -885,23 +886,23 @@ after a given number of event loop "ticks". ### tick(x, cb) -* `x` [<number>] Number of event loop "ticks". -* `cb` [<Function>] A callback function. +* `x` [<number>][] Number of event loop "ticks". +* `cb` [<Function>][] A callback function. ## tmpdir Module The `tmpdir` module supports the use of a temporary directory for testing. ### path -* [<string>] +* [<string>][] The realpath of the testing temporary directory. -### refresh([opts]) +### refresh(\[opts\]) -* `opts` [<Object>] (optional) Extra options. - * `spawn` [<boolean>] (default: `true`) Indicates that `refresh` is allowed - to optionally spawn a subprocess. +* `opts` [<Object>][] (optional) Extra options. + * `spawn` [<boolean>][] (default: `true`) Indicates that `refresh` is + allowed to optionally spawn a subprocess. Deletes and recreates the testing temporary directory. @@ -929,8 +930,9 @@ A driver class for running WPT with the WPT harness in a vm. See [the WPT tests README][] for details. [<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 +[<ArrayBufferView>]: https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView [<Buffer>]: https://nodejs.org/api/buffer.html#buffer_class_buffer +[<BufferSource>]: https://developer.mozilla.org/en-US/docs/Web/API/BufferSource [<Function>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function [<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 diff --git a/tools/icu/README.md b/tools/icu/README.md index 51b58455b4..89a70e7087 100644 --- a/tools/icu/README.md +++ b/tools/icu/README.md @@ -128,9 +128,9 @@ ICU in the future. As of this writing, however, the tools are separate entities within Node.js, although theyare being scrutinized by interested members of the ICU-TC. The “upstream” ICU bugs are given below. - * [#10919](http://bugs.icu-project.org/trac/ticket/10919) - (experimental branch - may copy any source patches here) - * [#10922](http://bugs.icu-project.org/trac/ticket/10922) - (data packaging improvements) - * [#10923](http://bugs.icu-project.org/trac/ticket/10923) - (rewrite data building in python) +* [#10919](http://bugs.icu-project.org/trac/ticket/10919) + (experimental branch - may copy any source patches here) +* [#10922](http://bugs.icu-project.org/trac/ticket/10922) + (data packaging improvements) +* [#10923](http://bugs.icu-project.org/trac/ticket/10923) + (rewrite data building in python) |