doc, tools: formalize, unify and codify default values

[vsemozhetbyt]

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
}

[vsemozhetbyt]

CI-lite: https://ci.nodejs.org/job/node-test-pull-request-lite/379/

[vsemozhetbyt]

cc @nodejs/documentation

[Trott]

This is not a sentence so I don't think a . at the end makes sense here. Same for the line below.

[Trott]

Remove the period after fences if we're putting one after the parenthetical.

[Trott]

Again, this is a list and not a sentence, so I don't think it warrants punctuation at the end. Same for the line below.

[Trott]

I'll stop after this one, but basically I don't think that we should put periods after values that aren't otherwise part of a sentence or even a phrase.

[vsemozhetbyt]

Will undo,

[vsemozhetbyt]

I've removed the periods if:

• default value statement is not a sentence;
• default value statement is not after a sentence (is not after a period).

[vsemozhetbyt]

CI-lite: https://ci.nodejs.org/job/node-test-pull-request-lite/391/

[Trott]

Still not a fan of all the added periods, but at least they're consistent, so non-blocking objection. But if you want my opinion on where periods should and shouldn't go, let me know. :-D

[vsemozhetbyt]

As a not native speaker, I definitely need to understand more) So if you add some notes, I will edit accordingly.

[Trott]

As a not native speaker, I definitely need to understand more) So if you add some notes, I will edit accordingly.

I'm having a lot of trouble finding examples in documentation (of other languages) or in style guides to support the approach I would suggest. And what I am finding basically amounts to "There are no definite rules other than to be consistent." So maybe best to just go with the approach you have here.

(I would expect that **Default**: 'some value' would never be followed by a period. Rather than adding a period everywhere for consistency, I'd remove the period everywhere for consistency. But like I said, I can't find a lot of support for that anywhere, and I'm not sure "because @Trott likes it" is a good enough reason!)

[Trott]

Thinking more on it: "Always add a period" does have the advantage that it requires no debate/decision to be made. It's simple. I think I may be coming around to your approach. :-D

[vsemozhetbyt]

Human language is a live tricky thing)
So we can leave it as is for now unless somebody would have a strong opinion otherwise?)

[vsemozhetbyt]

What I was thinking about the second edition:

* `param` {type} **Default**: `some value`

is hardly a sentence or phrase, more likely a tag, a formal construction.
While

* `param` {type} This a foo that makes bar be baz. **Default**: `some value`.

is a story, a narrative, a natural flow, and its momentum makes even partial phrases be more sentence-like, as a sentence with an ellipsis.

[vsemozhetbyt]

Landed in 237cbe1

[targos]

Should this be backported to v9.x-staging? If yes please follow the guide and raise a backport PR, if not let me know or add the dont-land-on label.

[vsemozhetbyt]

Backport to v9: #19793

[MylesBorins]

Should this be backported to v8.x-staging? If yes please follow the guide and raise a backport PR, if not let me know or add the dont-land-on label.

[vsemozhetbyt]

Backport to v8: #22388