doc: use code markup/markdown in headers

This also allows us to remove backslash escaping for `[` and `]`
inside of header code, which makes the bare markdown more readable.

Refs: https://github.com/nodejs/node/pull/31086

PR-URL: https://github.com/nodejs/node/pull/31149
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Beth Griggs <Bethany.Griggs@uk.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
This commit is contained in:
Ruben Bridgewater authored and Rich Trott committed 2020-01-03 19:31:52 -08:00
1 parent 84b15ebf24
commit f64842adeb
5 files changed
+142 -99

No files matched your search

+8 -7
View File
@@ -14,9 +14,9 @@ codebase not related to stylistic issues.
* [Align function arguments vertically](#align-function-arguments-vertically)
* [Initialization lists](#initialization-lists)
* [CamelCase for methods, functions, and classes](#camelcase-for-methods-functions-and-classes)
* [snake\_case for local variables and parameters](#snake_case-for-local-variables-and-parameters)
* [snake\_case\_ for private class fields](#snake_case_-for-private-class-fields)
* [snake\_case for C-like structs](#snake_case-for-c-like-structs)
* [`snake_case` for local variables and parameters](#snake_case-for-local-variables-and-parameters)
* [`snake_case_` for private class fields](#snake_case_-for-private-class-fields)
* [`snake_case` for C-like structs](#snake_case-for-c-like-structs)
* [Space after `template`](#space-after-template)
* [Memory Management](#memory-management)
* [Memory allocation](#memory-allocation)
@@ -155,7 +155,7 @@ class FooBar {
};
```
### snake\_case for local variables and parameters
### `snake_case` for local variables and parameters
```c++
int FunctionThatDoesSomething(const char* important_string) {
@@ -163,7 +163,7 @@ int FunctionThatDoesSomething(const char* important_string) {
}
```
### snake\_case\_ for private class fields
### `snake_case_` for private class fields
```c++
class Foo {
@@ -172,8 +172,9 @@ class Foo {
};
```
### snake\_case for C-like structs
For plain C-like structs snake_case can be used.
### `snake_case` for C-like structs
For `plain C-like structs snake_case can be used.
```c++
struct foo_bar {
+4 -4
View File
@@ -74,21 +74,21 @@ 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](writing-and-running-benchmarks.md#basics-of-a-benchmark).
### default\_http\_benchmarker
### `default_http_benchmarker`
The default benchmarker used to run HTTP benchmarks.
See [the guide on writing HTTP benchmarks](writing-and-running-benchmarks.md#creating-an-http-benchmark).
### PORT
### `PORT`
The default port used to run HTTP benchmarks.
See [the guide on writing HTTP benchmarks](writing-and-running-benchmarks.md#creating-an-http-benchmark).
### sendResult(data)
### `sendResult(data)`
Used in special benchmarks that can't use `createBenchmark` and the object
it returns to accomplish what they need. This function reports timing
+1 -1
View File
@@ -5093,7 +5093,7 @@ changes:
The `Promise` is resolved with the [`fs.Stats`][] object for the given `path`.
### `fsPromises.symlink(target, path\[, type\])`
### `fsPromises.symlink(target, path[, type])`
<!-- YAML
added: v10.0.0
-->
+1 -1
View File
@@ -3233,7 +3233,7 @@ const server = http2.createServer((req, res) => {
});
```
#### `response.setTimeout(msecs\[, callback\])`
#### `response.setTimeout(msecs[, callback])`
<!-- YAML
added: v8.4.0
-->
+128 -86
View File
@@ -27,7 +27,7 @@ This directory contains modules used to test the Node.js implementation.
The `benchmark` module is used by tests to run benchmarks.
### runBenchmark(name, args, env)
### `runBenchmark(name, args, env)`
* `name` [&lt;string>][] Name of benchmark suite to be run.
* `args` [&lt;Array>][] Array of environment variable key/value pairs (ex:
@@ -39,13 +39,15 @@ The `benchmark` module is used by tests to run benchmarks.
The `common` module is used by tests for consistency across repeated
tasks.
### allowGlobals(...whitelist)
### `allowGlobals(...whitelist)`
* `whitelist` [&lt;Array>][] Array of Globals
* return [&lt;Array>][]
Takes `whitelist` and concats that with predefined `knownGlobals`.
### canCreateSymLink()
### `canCreateSymLink()`
* return [&lt;boolean>][]
Checks whether the current running process can create symlinks. On Windows, this
@@ -54,11 +56,11 @@ symlinks
([SeCreateSymbolicLinkPrivilege](https://msdn.microsoft.com/en-us/library/windows/desktop/bb530716(v=vs.85).aspx)).
On non-Windows platforms, this always returns `true`.
### createZeroFilledFile(filename)
### `createZeroFilledFile(filename)`
Creates a 10 MB file of all null characters.
### disableCrashOnUnhandledRejection()
### `disableCrashOnUnhandledRejection()`
Removes the `process.on('unhandledRejection')` handler that crashes the process
after a tick. The handler is useful for tests that use Promises and need to make
@@ -66,12 +68,14 @@ sure no unexpected rejections occur, because currently they result in silent
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
### `enoughTestMem`
* [&lt;boolean>][]
Indicates if there is more than 1gb of total memory.
### expectsError(validator\[, exact\])
### `expectsError(validator[, exact])`
* `validator` [&lt;Object>][] | [&lt;RegExp>][] | [&lt;Function>][] |
[&lt;Error>][] The validator behaves identical to
`assert.throws(fn, validator)`.
@@ -83,7 +87,8 @@ validated using `assert.throws(() => { throw error; }, validator)`. If the
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\]\])
### `expectWarning(name[, expected[, code]])`
* `name` [&lt;string>][] | [&lt;Object>][]
* `expected` [&lt;string>][] | [&lt;Array>][] | [&lt;Object>][]
* `code` [&lt;string>][]
@@ -129,37 +134,42 @@ expectWarning({
});
```
### getArrayBufferViews(buf)
### `getArrayBufferViews(buf)`
* `buf` [&lt;Buffer>][]
* return [&lt;ArrayBufferView>][]\[\]
Returns an instance of all possible `ArrayBufferView`s of the provided Buffer.
### getBufferSources(buf)
### `getBufferSources(buf)`
* `buf` [&lt;Buffer>][]
* return [&lt;BufferSource>][]\[\]
Returns an instance of all possible `BufferSource`s of the provided Buffer,
consisting of all `ArrayBufferView` and an `ArrayBuffer`.
### getCallSite(func)
### `getCallSite(func)`
* `func` [&lt;Function>][]
* return [&lt;string>][]
Returns the file name and line number for the provided Function.
### getTTYfd()
### `getTTYfd()`
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
### `hasCrypto`
* [&lt;boolean>][]
Indicates whether OpenSSL is available.
### hasFipsCrypto
### `hasFipsCrypto`
* [&lt;boolean>][]
Indicates that Node.js has been linked with a FIPS compatible OpenSSL library,
@@ -169,83 +179,99 @@ To only detect if the OpenSSL library is FIPS compatible, regardless if it has
been enabled or not, then `process.config.variables.openssl_is_fips` can be
used to determine that situation.
### hasIntl
### `hasIntl`
* [&lt;boolean>][]
Indicates if [internationalization][] is supported.
### hasIPv6
### `hasIPv6`
* [&lt;boolean>][]
Indicates whether `IPv6` is supported on this platform.
### hasMultiLocalhost
### `hasMultiLocalhost`
* [&lt;boolean>][]
Indicates if there are multiple localhosts available.
### inFreeBSDJail
### `inFreeBSDJail`
* [&lt;boolean>][]
Checks whether free BSD Jail is true or false.
### isAIX
### `isAIX`
* [&lt;boolean>][]
Platform check for Advanced Interactive eXecutive (AIX).
### isAlive(pid)
### `isAlive(pid)`
* `pid` [&lt;number>][]
* return [&lt;boolean>][]
Attempts to 'kill' `pid`
### isFreeBSD
### `isFreeBSD`
* [&lt;boolean>][]
Platform check for Free BSD.
### isIBMi
### `isIBMi`
* [&lt;boolean>][]
Platform check for IBMi.
### isLinux
### `isLinux`
* [&lt;boolean>][]
Platform check for Linux.
### isLinuxPPCBE
### `isLinuxPPCBE`
* [&lt;boolean>][]
Platform check for Linux on PowerPC.
### isOSX
### `isOSX`
* [&lt;boolean>][]
Platform check for macOS.
### isSunOS
### `isSunOS`
* [&lt;boolean>][]
Platform check for SunOS.
### isWindows
### `isWindows`
* [&lt;boolean>][]
Platform check for Windows.
### localhostIPv4
### `localhostIPv4`
* [&lt;string>][]
IP of `localhost`.
### localIPv6Hosts
### `localIPv6Hosts`
* [&lt;Array>][]
Array of IPV6 representations for `localhost`.
### mustCall(\[fn\]\[, exact\])
### `mustCall([fn][, exact])`
* `fn` [&lt;Function>][] default = () => {}
* `exact` [&lt;number>][] default = 1
* return [&lt;Function>][]
@@ -256,7 +282,8 @@ fail.
If `fn` is not provided, an empty function will be used.
### mustCallAtLeast(\[fn\]\[, minimum\])
### `mustCallAtLeast([fn][, minimum])`
* `fn` [&lt;Function>][] default = () => {}
* `minimum` [&lt;number>][] default = 1
* return [&lt;Function>][]
@@ -267,14 +294,16 @@ fail.
If `fn` is not provided, an empty function will be used.
### mustNotCall(\[msg\])
### `mustNotCall([msg])`
* `msg` [&lt;string>][] default = 'function should not have been called'
* return [&lt;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)
### `nodeProcessAborted(exitCode, signal)`
* `exitCode` [&lt;number>][]
* `signal` [&lt;string>][]
* return [&lt;boolean>][]
@@ -283,12 +312,14 @@ 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
### `opensslCli`
* [&lt;boolean>][]
Indicates whether 'opensslCli' is supported.
### platformTimeout(ms)
### `platformTimeout(ms)`
* `ms` [&lt;number>][] | [&lt;bigint>][]
* return [&lt;number>][] | [&lt;bigint>][]
@@ -296,22 +327,26 @@ 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
### `PIPE`
* [&lt;string>][]
Path to the test socket.
### PORT
### `PORT`
* [&lt;number>][]
A port number for tests to use if one is needed.
### printSkipMessage(msg)
### `printSkipMessage(msg)`
* `msg` [&lt;string>][]
Logs '1..0 # Skipped: ' + `msg`
### pwdCommand
### `pwdCommand`
* [&lt;array>][] First two argument for the `spawn`/`exec` functions.
Platform normalized `pwd` command options. Usage example:
@@ -322,12 +357,14 @@ const { spawn } = require('child_process');
spawn(...common.pwdCommand, { stdio: ['pipe'] });
```
### rootDir
### `rootDir`
* [&lt;string>][]
Path to the 'root' directory. either `/` or `c:\\` (windows)
### runWithInvalidFD(func)
### `runWithInvalidFD(func)`
* `func` [&lt;Function>][]
Runs `func` with an invalid file descriptor that is an unsigned integer and
@@ -335,27 +372,28 @@ can be used to trigger `EBADF` as the first argument. If no such file
descriptor could be generated, a skip message will be printed and the `func`
will not be run.
### skip(msg)
### `skip(msg)`
* `msg` [&lt;string>][]
Logs '1..0 # Skipped: ' + `msg` and exits with exit code `0`.
### skipIfEslintMissing()
### `skipIfEslintMissing()`
Skip the rest of the tests in the current file when `ESLint` is not available
at `tools/node_modules/eslint`
### skipIfInspectorDisabled()
### `skipIfInspectorDisabled()`
Skip the rest of the tests in the current file when the Inspector
was disabled at compile time.
### skipIf32Bits()
### `skipIf32Bits()`
Skip the rest of the tests in the current file when the Node.js executable
was compiled with a pointer size smaller than 64 bits.
### skipIfWorker()
### `skipIfWorker()`
Skip the rest of the tests in the current file when not running on a main
thread.
@@ -394,18 +432,18 @@ countdown.dec();
countdown.dec();
```
### new Countdown(limit, callback)
### `new Countdown(limit, callback)`
* `limit` {number}
* `callback` {function}
Creates a new `Countdown` instance.
### Countdown.prototype.dec()
### `Countdown.prototype.dec()`
Decrements the `Countdown` counter.
### Countdown.prototype.remaining
### `Countdown.prototype.remaining`
Specifies the remaining number of times `Countdown.prototype.dec()` must be
called before the callback is invoked.
@@ -414,20 +452,20 @@ called before the callback is invoked.
The `cpu-prof` module provides utilities related to CPU profiling tests.
### env
### `env`
* Default: { ...process.env, NODE_DEBUG_NATIVE: 'INSPECTOR_PROFILER' }
Environment variables used in profiled processes.
### getCpuProfiles(dir)
### `getCpuProfiles(dir)`
* `dir` {string} The directory containing the CPU profile files.
* return [&lt;string>][]
Returns an array of all `.cpuprofile` files found in `dir`.
### getFrames(file, suffix)
### `getFrames(file, suffix)`
* `file` {string} Path to a `.cpuprofile` file.
* `suffix` {string} Suffix of the URL of call frames to retrieve.
@@ -436,11 +474,11 @@ Returns an array of all `.cpuprofile` files found in `dir`.
Returns an object containing an array of the relevant call frames and an array
of all the profile nodes.
### kCpuProfInterval
### `kCpuProfInterval`
Sampling interval in microseconds.
### verifyFrames(output, file, suffix)
### `verifyFrames(output, file, suffix)`
* `output` {string}
* `file` {string}
@@ -449,11 +487,11 @@ Sampling interval in microseconds.
Throws an `AssertionError` if there are no call frames with the expected
`suffix` in the profiling data contained in `file`.
## DNS Module
## `DNS` Module
The `DNS` module provides utilities related to the `dns` built-in module.
### errorLookupMock(code, syscall)
### `errorLookupMock(code, syscall)`
* `code` [&lt;string>][] Defaults to `dns.mockedErrorCode`.
* `syscall` [&lt;string>][] Defaults to `dns.mockedSysCall`.
@@ -463,15 +501,15 @@ 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()`.
### mockedErrorCode
### `mockedErrorCode`
The default `code` of errors generated by `errorLookupMock`.
### mockedSysCall
### `mockedSysCall`
The default `syscall` of errors generated by `errorLookupMock`.
### readDomainFromPacket(buffer, offset)
### `readDomainFromPacket(buffer, offset)`
* `buffer` [&lt;Buffer>][]
* `offset` [&lt;number>][]
@@ -480,7 +518,7 @@ The default `syscall` of errors generated by `errorLookupMock`.
Reads the domain string from a packet and returns an object containing the
number of bytes read and the domain.
### parseDNSPacket(buffer)
### `parseDNSPacket(buffer)`
* `buffer` [&lt;Buffer>][]
* return [&lt;Object>][]
@@ -488,21 +526,21 @@ number of bytes read and the domain.
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)
### `writeIPv6(ip)`
* `ip` [&lt;string>][]
* return [&lt;Buffer>][]
Reads an IPv6 String and returns a Buffer containing the parts.
### writeDomainName(domain)
### `writeDomainName(domain)`
* `domain` [&lt;string>][]
* return [&lt;Buffer>][]
Reads a Domain String and returns a Buffer containing the domain.
### writeDNSPacket(parsed)
### `writeDNSPacket(parsed)`
* `parsed` [&lt;Object>][]
* return [&lt;Buffer>][]
@@ -523,16 +561,16 @@ There is no difference between client or server side beyond their names.
The behavior of the Node.js test suite can be altered using the following
environment variables.
### NODE_COMMON_PORT
### `NODE_COMMON_PORT`
If set, `NODE_COMMON_PORT`'s value overrides the `common.PORT` default value of
12346.
### NODE_SKIP_FLAG_CHECK
### `NODE_SKIP_FLAG_CHECK`
If set, command line arguments passed to individual tests are not validated.
### NODE_TEST_KNOWN_GLOBALS
### `NODE_TEST_KNOWN_GLOBALS`
A comma-separated list of variables names that are appended to the global
variable whitelist. Alternatively, if `NODE_TEST_KNOWN_GLOBALS` is set to `'0'`,
@@ -543,26 +581,26 @@ global leak detection is disabled.
The `common/fixtures` module provides convenience methods for working with
files in the `test/fixtures` directory.
### fixtures.fixturesDir
### `fixtures.fixturesDir`
* [&lt;string>][]
The absolute path to the `test/fixtures/` directory.
### fixtures.path(...args)
### `fixtures.path(...args)`
* `...args` [&lt;string>][]
Returns the result of `path.join(fixtures.fixturesDir, ...args)`.
### fixtures.readSync(args\[, enc\])
### `fixtures.readSync(args[, enc])`
* `args` [&lt;string>][] | [&lt;Array>][]
Returns the result of
`fs.readFileSync(path.join(fixtures.fixturesDir, ...args), 'enc')`.
### fixtures.readKey(arg\[, enc\])
### `fixtures.readKey(arg[, enc])`
* `arg` [&lt;string>][]
@@ -574,14 +612,14 @@ Returns the result of
This provides utilities for checking the validity of heap dumps.
This requires the usage of `--expose-internals`.
### heap.recordState()
### `heap.recordState()`
Create a heap dump and an embedder graph copy for inspection.
The returned object has a `validateSnapshotNodes` function similar to the
one listed below. (`heap.validateSnapshotNodes(...)` is a shortcut for
`heap.recordState().validateSnapshotNodes(...)`.)
### heap.validateSnapshotNodes(name, expected, options)
### `heap.validateSnapshotNodes(name, expected, options)`
* `name` [&lt;string>][] Look for this string as the name of heap dump nodes.
* `expected` [&lt;Array>][] A list of objects, possibly with an `children`
@@ -622,7 +660,8 @@ hijackStdout((data) => {
console.log('this is sent to the hijacked listener');
```
### hijackStderr(listener)
### `hijackStderr(listener)`
* `listener` [&lt;Function>][]: a listener with a single parameter
called `data`.
@@ -631,7 +670,8 @@ 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)
### `hijackStdout(listener)`
* `listener` [&lt;Function>][]: a listener with a single parameter
called `data`.
@@ -727,7 +767,7 @@ const frame = new http2.SettingsFrame(ack);
socket.write(frame.data);
```
### http2.kFakeRequestHeaders
### `http2.kFakeRequestHeaders`
Set to a `Buffer` instance that contains a minimal set of serialized HTTP/2
request headers to be used as the payload of a `http2.HeadersFrame`.
@@ -739,7 +779,7 @@ const frame = new http2.HeadersFrame(1, http2.kFakeRequestHeaders, 0, true);
socket.write(frame.data);
```
### http2.kFakeResponseHeaders
### `http2.kFakeResponseHeaders`
Set to a `Buffer` instance that contains a minimal set of serialized HTTP/2
response headers to be used as the payload a `http2.HeadersFrame`.
@@ -751,7 +791,7 @@ const frame = new http2.HeadersFrame(1, http2.kFakeResponseHeaders, 0, true);
socket.write(frame.data);
```
### http2.kClientMagic
### `http2.kClientMagic`
Set to a `Buffer` containing the preamble bytes an HTTP/2 client must send
upon initial establishment of a connection.
@@ -766,7 +806,7 @@ socket.write(http2.kClientMagic);
The `common/internet` module provides utilities for working with
internet-related tests.
### internet.addresses
### `internet.addresses`
* [&lt;Object>][]
* `INET_HOST` [&lt;string>][] A generic host that has registered common
@@ -807,7 +847,8 @@ const onGC = require('../common/ongc');
onGC({}, { ongc() { console.log('collected'); } });
```
### onGC(target, listener)
### `onGC(target, listener)`
* `target` [&lt;Object>][]
* `listener` [&lt;Object>][]
* `ongc` [&lt;Function>][]
@@ -827,7 +868,7 @@ should not be in scope when `listener.ongc()` is created.
The `report` module provides helper functions for testing diagnostic reporting
functionality.
### findReports(pid, dir)
### `findReports(pid, dir)`
* `pid` [&lt;number>][] Process ID to retrieve diagnostic report files for.
* `dir` [&lt;string>][] Directory to search for diagnostic report files.
@@ -836,14 +877,14 @@ functionality.
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)
### `validate(filepath)`
* `filepath` [&lt;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)
### `validateContent(report)`
* `report` [&lt;Object>][] | [&lt;string>][] JSON contents of a diagnostic
report file, the parsed Object thereof, or the result of
@@ -857,7 +898,7 @@ Validates the schema of a diagnostic report whose content is specified in
The `tick` module provides a helper function that can be used to call a callback
after a given number of event loop "ticks".
### tick(x, cb)
### `tick(x, cb)`
* `x` [&lt;number>][] Number of event loop "ticks".
* `cb` [&lt;Function>][] A callback function.
@@ -866,12 +907,13 @@ after a given number of event loop "ticks".
The `tmpdir` module supports the use of a temporary directory for testing.
### path
### `path`
* [&lt;string>][]
The realpath of the testing temporary directory.
### refresh()
### `refresh()`
Deletes and recreates the testing temporary directory.
@@ -884,7 +926,7 @@ parent.
## WPT Module
### harness
### `harness`
A legacy port of [Web Platform Tests][] harness.