doc, tools: formalize, unify and codify default values #19737

vsemozhetbyt · 2018-04-02T02:52:24Z

Checklist

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

Status Quo

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.
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

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.)
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 · 2018-04-02T02:53:30Z

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

vsemozhetbyt · 2018-04-02T03:07:54Z

cc @nodejs/documentation

Trott · 2018-04-02T03:39:57Z

doc/STYLE_GUIDE.md

@@ -16,8 +16,8 @@
 * Avoid personal pronouns in reference documentation ("I", "you", "we").
  * Personal pronouns are acceptable in colloquial documentation such as guides.
  * Use gender-neutral pronouns and gender-neutral plural nouns.
-    * OK: "they", "their", "them", "folks", "people", "developers"
-    * NOT OK: "his", "hers", "him", "her", "guys", "dudes"
+    * OK: "they", "their", "them", "folks", "people", "developers".


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

Trott · 2018-04-02T03:40:14Z

doc/STYLE_GUIDE.md

@@ -43,7 +43,7 @@
  * For illustrations, prefer SVG to other assets. When SVG is not feasible,
    please keep a close eye on the filesize of the asset you're introducing.
 * For code blocks:
-  * Use language aware fences. ("```js")
+  * Use language aware fences. ("```js").


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

Trott · 2018-04-02T03:40:47Z

doc/STYLE_GUIDE.md

 * Function returns should use the following format:
  * <code>* Returns: {type|type2} Optional description.</code>
  * E.g. <code>* Returns: {AsyncHook} A reference to `asyncHook`.</code>
 * Use official styling for capitalization in products and projects.
-  * OK: JavaScript, Google's V8
-  * NOT OK: Javascript, Google's v8
+  * OK: JavaScript, Google's V8.


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 · 2018-04-02T03:41:33Z

doc/api/assert.md

@@ -469,7 +469,7 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
 <!-- YAML
 added: v0.1.21
 -->
-* `message` {any} **Default:** `'Failed'`
+* `message` {any} **Default:** `'Failed'`.


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.

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 · 2018-04-02T08:09:44Z

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

Trott · 2018-04-02T18:20:14Z

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 · 2018-04-02T18:53:21Z

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

Trott · 2018-04-02T20:53:50Z

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 · 2018-04-02T20:54:35Z

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 · 2018-04-02T21:34:16Z

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 · 2018-04-02T21:42:27Z

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.

PR-URL: #19737 Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>

vsemozhetbyt · 2018-04-04T09:33:47Z

Landed in 237cbe1

targos · 2018-04-04T10:09:17Z

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 · 2018-04-04T12:55:03Z

Backport to v9: #19793

Backport-PR-URL: #19793 PR-URL: #19737 Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>

MylesBorins · 2018-08-17T19:57:12Z

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 · 2018-08-18T12:49:56Z

Backport to v8: #22388

Backport-PR-URL: #22388 PR-URL: #19737 Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 2, 2018

vsemozhetbyt added the tools Issues and PRs related to the tools directory. label Apr 2, 2018

devsnek approved these changes Apr 2, 2018

View reviewed changes

vsemozhetbyt added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 2, 2018

Trott reviewed Apr 2, 2018

View reviewed changes

vsemozhetbyt removed the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 2, 2018

vsemozhetbyt added 2 commits April 2, 2018 11:05

doc: formalize and unify default values

9b35e3f

doc, tools: codify default values formalization

53a7c8f

jasnell approved these changes Apr 2, 2018

View reviewed changes

trivikr approved these changes Apr 3, 2018

View reviewed changes

vsemozhetbyt added a commit that referenced this pull request Apr 4, 2018

doc,tools: formalize, unify, codify default values

237cbe1

PR-URL: #19737 Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>

vsemozhetbyt closed this Apr 4, 2018

vsemozhetbyt deleted the doc-tools-json-default branch April 4, 2018 09:34

targos added the backport-requested-v9.x label Apr 4, 2018

This was referenced Apr 4, 2018

[v9.x backport] crypto: add ECDH.convertKey to convert public keys #19745

Closed

[v9.x backport] doc, tools: formalize, unify and codify default values #19793

Closed

targos added backported-to-v9.x and removed backport-requested-v9.x labels Apr 6, 2018

vsemozhetbyt mentioned this pull request Aug 18, 2018

[v8.x backport] doc,tools: formalize, unify, codify default values #22388

Closed

3 tasks

MylesBorins mentioned this pull request Sep 6, 2018

v8.12.0 proposal #21593

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc, tools: formalize, unify and codify default values #19737

doc, tools: formalize, unify and codify default values #19737

vsemozhetbyt commented Apr 2, 2018 •

edited

Loading

vsemozhetbyt commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018

Trott Apr 2, 2018

Trott Apr 2, 2018

Trott Apr 2, 2018

Trott Apr 2, 2018 •

edited

Loading

vsemozhetbyt Apr 2, 2018

vsemozhetbyt Apr 2, 2018 •

edited

Loading

vsemozhetbyt commented Apr 2, 2018 •

edited

Loading

Trott commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018

Trott commented Apr 2, 2018

Trott commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018 •

edited

Loading

vsemozhetbyt commented Apr 4, 2018

targos commented Apr 4, 2018

vsemozhetbyt commented Apr 4, 2018

MylesBorins commented Aug 17, 2018

vsemozhetbyt commented Aug 18, 2018

doc, tools: formalize, unify and codify default values #19737

doc, tools: formalize, unify and codify default values #19737

Conversation

vsemozhetbyt commented Apr 2, 2018 • edited Loading

Checklist

Status Quo

Fixing strategy

Results

vsemozhetbyt commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018

Trott Apr 2, 2018

Choose a reason for hiding this comment

Trott Apr 2, 2018

Choose a reason for hiding this comment

Trott Apr 2, 2018

Choose a reason for hiding this comment

Trott Apr 2, 2018 • edited Loading

Choose a reason for hiding this comment

vsemozhetbyt Apr 2, 2018

Choose a reason for hiding this comment

vsemozhetbyt Apr 2, 2018 • edited Loading

Choose a reason for hiding this comment

vsemozhetbyt commented Apr 2, 2018 • edited Loading

Trott commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018

Trott commented Apr 2, 2018

Trott commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018 • edited Loading

vsemozhetbyt commented Apr 4, 2018

targos commented Apr 4, 2018

vsemozhetbyt commented Apr 4, 2018

MylesBorins commented Aug 17, 2018

vsemozhetbyt commented Aug 18, 2018

vsemozhetbyt commented Apr 2, 2018 •

edited

Loading

Trott Apr 2, 2018 •

edited

Loading

vsemozhetbyt Apr 2, 2018 •

edited

Loading

vsemozhetbyt commented Apr 2, 2018 •

edited

Loading

vsemozhetbyt commented Apr 2, 2018 •

edited

Loading