Skip to content

doc, tools: formalize, unify and codify default values

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines

Status Quo

  1. The format of default values is defined in STYLE_GUIDE.md. But the current state of sources is not unified: many default values are stated in informal ways or with tiny deviations.

  2. tools/doc/json.js has an obsolete RegExp to detect the default values in parameter lists. Because of this, only one default field is added to JSON docs, and even this is detected wrongly: this source produces this item:

{
  "textRaw": "`undefined` (default): use [`http.globalAgent`][] for this host and port. ",
  "name": "undefined",
- "default": "",
- "desc": ": use [`http.globalAgent`][] for this host and port."
}

insstead of:

{
  "textRaw": "`undefined` (default): use [`http.globalAgent`][] for this host and port. ",
  "name": "undefined",
+ "desc": "(default): use [`http.globalAgent`][] for this host and port."
}

Fixing strategy

  1. The first commit formalizes and unifies doc sources: informal definitions are replaced by formal ones, deviating nits in the formal definitions are unified (definitions are moved to the end, backticks and periods are added, duplicate info is removed etc.)

  2. The second commit codifies default values format: periods are added to STYLE_GUIDE.md and RegExp in tools/doc/json.js is replaced by the actual one.

Results

  • Doc sources are unified and often fixed.
  • ~340 default values are moved from description blobs to default value fields in JSON docs.
  • The mentioned false-positive case is fixed.

JSON example of old and new state in diff:

{
  "textRaw": "`code` {integer} The exit code. **Default:** `0`. ",
  "name": "code",
  "type": "integer",
- "desc": "The exit code. **Default:** `0`.",
  "optional": true
}

{
  "textRaw": "`code` {integer} The exit code. **Default:** `0`. ",
  "name": "code",
+ "default": "`0`",
  "type": "integer",
+ "desc": "The exit code.",
  "optional": true
}

Merge request reports

Loading