From 808f025bea26f004fd7665ce084819f0395b8253 Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Wed, 1 Jan 2020 17:44:16 +0100 Subject: [PATCH] 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 Reviewed-By: Anto Aravinth Reviewed-By: Beth Griggs Reviewed-By: James M Snell Reviewed-By: Trivikram Kamat Reviewed-By: Rich Trott --- CPP_STYLE_GUIDE.md | 15 +-- benchmark/README.md | 8 +- doc/api/fs.md | 2 +- doc/api/http2.md | 2 +- test/common/README.md | 213 +++++++++++++++++++++++++----------------- 5 files changed, 141 insertions(+), 99 deletions(-) diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index f29c8df3210caa..1a578b970ae515 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -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 { diff --git a/benchmark/README.md b/benchmark/README.md index 7e027c6e76f7b8..c5fdad093471b5 100644 --- a/benchmark/README.md +++ b/benchmark/README.md @@ -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 diff --git a/doc/api/fs.md b/doc/api/fs.md index a45e171e352dbb..db691d89afeb43 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -5073,7 +5073,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])` diff --git a/doc/api/http2.md b/doc/api/http2.md index 32333d0feb4d5d..3f7ca83fcc222b 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -3249,7 +3249,7 @@ const server = http2.createServer((req, res) => { }); ``` -#### `response.setTimeout(msecs\[, callback\])` +#### `response.setTimeout(msecs[, callback])` diff --git a/test/common/README.md b/test/common/README.md index 980a02e3ee891e..a85dd6663e5852 100644 --- a/test/common/README.md +++ b/test/common/README.md @@ -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` [<string>][] Name of benchmark suite to be run. * `args` [<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` [<Array>][] Array of Globals * return [<Array>][] Takes `whitelist` and concats that with predefined `knownGlobals`. -### canCreateSymLink() +### `canCreateSymLink()` + * return [<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,13 @@ 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` + * [<boolean>][] Indicates if there is more than 1gb of total memory. -### expectsError(\[fn, \]settings\[, exact\]) +### `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 @@ -110,7 +113,8 @@ 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\]\]) +### `expectWarning(name[, expected[, code]])` + * `name` [<string>][] | [<Object>][] * `expected` [<string>][] | [<Array>][] | [<Object>][] * `code` [<string>][] @@ -156,37 +160,42 @@ expectWarning({ }); ``` -### getArrayBufferViews(buf) +### `getArrayBufferViews(buf)` + * `buf` [<Buffer>][] * return [<ArrayBufferView>][]\[\] Returns an instance of all possible `ArrayBufferView`s of the provided Buffer. -### getBufferSources(buf) +### `getBufferSources(buf)` + * `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) +### `getCallSite(func)` + * `func` [<Function>][] * return [<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` + * [<boolean>][] Indicates whether OpenSSL is available. -### hasFipsCrypto +### `hasFipsCrypto` + * [<boolean>][] Indicates that Node.js has been linked with a FIPS compatible OpenSSL library, @@ -196,83 +205,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` + * [<boolean>][] Indicates if [internationalization][] is supported. -### hasIPv6 +### `hasIPv6` + * [<boolean>][] Indicates whether `IPv6` is supported on this platform. -### hasMultiLocalhost +### `hasMultiLocalhost` + * [<boolean>][] Indicates if there are multiple localhosts available. -### inFreeBSDJail +### `inFreeBSDJail` + * [<boolean>][] Checks whether free BSD Jail is true or false. -### isAIX +### `isAIX` + * [<boolean>][] Platform check for Advanced Interactive eXecutive (AIX). -### isAlive(pid) +### `isAlive(pid)` + * `pid` [<number>][] * return [<boolean>][] Attempts to 'kill' `pid` -### isFreeBSD +### `isFreeBSD` + * [<boolean>][] Platform check for Free BSD. -### isIBMi +### `isIBMi` + * [<boolean>][] Platform check for IBMi. -### isLinux +### `isLinux` + * [<boolean>][] Platform check for Linux. -### isLinuxPPCBE +### `isLinuxPPCBE` + * [<boolean>][] Platform check for Linux on PowerPC. -### isOSX +### `isOSX` + * [<boolean>][] Platform check for macOS. -### isSunOS +### `isSunOS` + * [<boolean>][] Platform check for SunOS. -### isWindows +### `isWindows` + * [<boolean>][] Platform check for Windows. -### localhostIPv4 +### `localhostIPv4` + * [<string>][] IP of `localhost`. -### localIPv6Hosts +### `localIPv6Hosts` + * [<Array>][] Array of IPV6 representations for `localhost`. -### mustCall(\[fn\]\[, exact\]) +### `mustCall([fn][, exact])` + * `fn` [<Function>][] default = () => {} * `exact` [<number>][] default = 1 * return [<Function>][] @@ -283,7 +308,8 @@ fail. If `fn` is not provided, an empty function will be used. -### mustCallAtLeast(\[fn\]\[, minimum\]) +### `mustCallAtLeast([fn][, minimum])` + * `fn` [<Function>][] default = () => {} * `minimum` [<number>][] default = 1 * return [<Function>][] @@ -294,14 +320,16 @@ fail. If `fn` is not provided, an empty function will be used. -### mustNotCall(\[msg\]) +### `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) +### `nodeProcessAborted(exitCode, signal)` + * `exitCode` [<number>][] * `signal` [<string>][] * return [<boolean>][] @@ -310,12 +338,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` + * [<boolean>][] Indicates whether 'opensslCli' is supported. -### platformTimeout(ms) +### `platformTimeout(ms)` + * `ms` [<number>][] | [<bigint>][] * return [<number>][] | [<bigint>][] @@ -323,22 +353,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` + * [<string>][] Path to the test socket. -### PORT +### `PORT` + * [<number>][] A port number for tests to use if one is needed. -### printSkipMessage(msg) +### `printSkipMessage(msg)` + * `msg` [<string>][] Logs '1..0 # Skipped: ' + `msg` -### pwdCommand +### `pwdCommand` + * [<array>][] First two argument for the `spawn`/`exec` functions. Platform normalized `pwd` command options. Usage example: @@ -349,12 +383,14 @@ const { spawn } = require('child_process'); spawn(...common.pwdCommand, { stdio: ['pipe'] }); ``` -### rootDir +### `rootDir` + * [<string>][] Path to the 'root' directory. either `/` or `c:\\` (windows) -### runWithInvalidFD(func) +### `runWithInvalidFD(func)` + * `func` [<Function>][] Runs `func` with an invalid file descriptor that is an unsigned integer and @@ -362,27 +398,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` [<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. @@ -421,18 +458,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. @@ -441,20 +478,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 [<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. @@ -463,11 +500,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} @@ -476,11 +513,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` [<string>][] Defaults to `dns.mockedErrorCode`. * `syscall` [<string>][] Defaults to `dns.mockedSysCall`. @@ -490,15 +527,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` [<Buffer>][] * `offset` [<number>][] @@ -507,7 +544,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` [<Buffer>][] * return [<Object>][] @@ -515,21 +552,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` [<string>][] * return [<Buffer>][] Reads an IPv6 String and returns a Buffer containing the parts. -### writeDomainName(domain) +### `writeDomainName(domain)` * `domain` [<string>][] * return [<Buffer>][] Reads a Domain String and returns a Buffer containing the domain. -### writeDNSPacket(parsed) +### `writeDNSPacket(parsed)` * `parsed` [<Object>][] * return [<Buffer>][] @@ -550,16 +587,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'`, @@ -570,26 +607,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` * [<string>][] The absolute path to the `test/fixtures/` directory. -### fixtures.path(...args) +### `fixtures.path(...args)` * `...args` [<string>][] Returns the result of `path.join(fixtures.fixturesDir, ...args)`. -### fixtures.readSync(args\[, enc\]) +### `fixtures.readSync(args[, enc])` * `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>][] @@ -601,14 +638,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` [<string>][] Look for this string as the name of heap dump nodes. * `expected` [<Array>][] A list of objects, possibly with an `children` @@ -649,7 +686,8 @@ hijackStdout((data) => { console.log('this is sent to the hijacked listener'); ``` -### hijackStderr(listener) +### `hijackStderr(listener)` + * `listener` [<Function>][]: a listener with a single parameter called `data`. @@ -658,7 +696,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` [<Function>][]: a listener with a single parameter called `data`. @@ -754,7 +793,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`. @@ -766,7 +805,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`. @@ -778,7 +817,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. @@ -793,7 +832,7 @@ socket.write(http2.kClientMagic); The `common/internet` module provides utilities for working with internet-related tests. -### internet.addresses +### `internet.addresses` * [<Object>][] * `INET_HOST` [<string>][] A generic host that has registered common @@ -834,7 +873,8 @@ const onGC = require('../common/ongc'); onGC({}, { ongc() { console.log('collected'); } }); ``` -### onGC(target, listener) +### `onGC(target, listener)` + * `target` [<Object>][] * `listener` [<Object>][] * `ongc` [<Function>][] @@ -854,7 +894,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` [<number>][] Process ID to retrieve diagnostic report files for. * `dir` [<string>][] Directory to search for diagnostic report files. @@ -863,14 +903,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` [<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` [<Object>][] | [<string>][] JSON contents of a diagnostic report file, the parsed Object thereof, or the result of @@ -884,7 +924,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` [<number>][] Number of event loop "ticks". * `cb` [<Function>][] A callback function. @@ -893,18 +933,19 @@ after a given number of event loop "ticks". The `tmpdir` module supports the use of a temporary directory for testing. -### path +### `path` + * [<string>][] The realpath of the testing temporary directory. -### refresh() +### `refresh()` Deletes and recreates the testing temporary directory. ## WPT Module -### harness +### `harness` A legacy port of [Web Platform Tests][] harness.