{"action":"created","issue":{"url":"https://api.github.com/repos/nodejs/node/issues/19737","repository_url":"https://api.github.com/repos/nodejs/node","labels_url":"https://api.github.com/repos/nodejs/node/issues/19737/labels{/name}","comments_url":"https://api.github.com/repos/nodejs/node/issues/19737/comments","events_url":"https://api.github.com/repos/nodejs/node/issues/19737/events","html_url":"https://github.com/nodejs/node/pull/19737","id":310380906,"number":19737,"title":"doc, tools: formalize, unify and codify default values","user":{"login":"vsemozhetbyt","id":10393198,"avatar_url":"https://avatars1.githubusercontent.com/u/10393198?v=4","gravatar_id":"","url":"https://api.github.com/users/vsemozhetbyt","html_url":"https://github.com/vsemozhetbyt","followers_url":"https://api.github.com/users/vsemozhetbyt/followers","following_url":"https://api.github.com/users/vsemozhetbyt/following{/other_user}","gists_url":"https://api.github.com/users/vsemozhetbyt/gists{/gist_id}","starred_url":"https://api.github.com/users/vsemozhetbyt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vsemozhetbyt/subscriptions","organizations_url":"https://api.github.com/users/vsemozhetbyt/orgs","repos_url":"https://api.github.com/users/vsemozhetbyt/repos","events_url":"https://api.github.com/users/vsemozhetbyt/events{/privacy}","received_events_url":"https://api.github.com/users/vsemozhetbyt/received_events","type":"User","site_admin":false},"labels":[{"id":155267517,"url":"https://api.github.com/repos/nodejs/node/labels/doc","name":"doc","color":"006b75","default":false},{"id":237979054,"url":"https://api.github.com/repos/nodejs/node/labels/tools","name":"tools","color":"d4c5f9","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":3,"created_at":"2018-04-02T02:52:24Z","updated_at":"2018-04-02T18:20:14Z","closed_at":null,"author_association":"MEMBER","pull_request":{"url":"https://api.github.com/repos/nodejs/node/pulls/19737","html_url":"https://github.com/nodejs/node/pull/19737","diff_url":"https://github.com/nodejs/node/pull/19737.diff","patch_url":"https://github.com/nodejs/node/pull/19737.patch"},"body":"##### Checklist\r\n- [x] `make -j4 test` (UNIX), or `vcbuild test` (Windows) passes\r\n- [x] documentation is changed or added\r\n- [x] commit message follows [commit guidelines](https://github.com/nodejs/node/blob/master/doc/guides/contributing/pull-requests.md#commit-message-guidelines)\r\n\r\n#### Status Quo\r\n\r\n1. The format of default values is defined in [STYLE_GUIDE.md](https://github.com/nodejs/node/blame/8ed0f3409a31abae87bf6aae394b8901c5e6ecab/doc/STYLE_GUIDE.md#L61-L63). But the current state of sources is not unified: many default values are stated in informal ways or with tiny deviations.\r\n\r\n2. `tools/doc/json.js` has [an obsolete RegExp](https://github.com/nodejs/node/blob/303354b4f7214388783037333dc82d64179b77cd/tools/doc/json.js#L402) 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](https://github.com/nodejs/node/blame/a29089d7c866955616c0e363843017e9b9b2a736/doc/api/http.md#L1851) produces this item:\r\n\r\n```diff\r\n{\r\n  \"textRaw\": \"`undefined` (default): use [`http.globalAgent`][] for this host and port. \",\r\n  \"name\": \"undefined\",\r\n- \"default\": \"\",\r\n- \"desc\": \": use [`http.globalAgent`][] for this host and port.\"\r\n}\r\n```\r\ninsstead of:\r\n```diff\r\n{\r\n  \"textRaw\": \"`undefined` (default): use [`http.globalAgent`][] for this host and port. \",\r\n  \"name\": \"undefined\",\r\n+ \"desc\": \"(default): use [`http.globalAgent`][] for this host and port.\"\r\n}\r\n```\r\n\r\n#### Fixing strategy\r\n\r\n1. 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.)\r\n\r\n2. 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.\r\n\r\n#### Results\r\n\r\n* Doc sources are unified and often fixed.\r\n* ~340 default values are moved from description blobs to default value fields in JSON docs.\r\n* The mentioned false-positive case is fixed.\r\n\r\nJSON example of old and new state in diff:\r\n```diff\r\n{\r\n  \"textRaw\": \"`code` {integer} The exit code. **Default:** `0`. \",\r\n  \"name\": \"code\",\r\n  \"type\": \"integer\",\r\n- \"desc\": \"The exit code. **Default:** `0`.\",\r\n  \"optional\": true\r\n}\r\n\r\n{\r\n  \"textRaw\": \"`code` {integer} The exit code. **Default:** `0`. \",\r\n  \"name\": \"code\",\r\n+ \"default\": \"`0`\",\r\n  \"type\": \"integer\",\r\n+ \"desc\": \"The exit code.\",\r\n  \"optional\": true\r\n}\r\n```"},"comment":{"url":"https://api.github.com/repos/nodejs/node/issues/comments/378000514","html_url":"https://github.com/nodejs/node/pull/19737#issuecomment-378000514","issue_url":"https://api.github.com/repos/nodejs/node/issues/19737","id":378000514,"user":{"login":"Trott","id":718899,"avatar_url":"https://avatars2.githubusercontent.com/u/718899?v=4","gravatar_id":"","url":"https://api.github.com/users/Trott","html_url":"https://github.com/Trott","followers_url":"https://api.github.com/users/Trott/followers","following_url":"https://api.github.com/users/Trott/following{/other_user}","gists_url":"https://api.github.com/users/Trott/gists{/gist_id}","starred_url":"https://api.github.com/users/Trott/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Trott/subscriptions","organizations_url":"https://api.github.com/users/Trott/orgs","repos_url":"https://api.github.com/users/Trott/repos","events_url":"https://api.github.com/users/Trott/events{/privacy}","received_events_url":"https://api.github.com/users/Trott/received_events","type":"User","site_admin":false},"created_at":"2018-04-02T18:20:14Z","updated_at":"2018-04-02T18:20:14Z","author_association":"OWNER","body":"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 "}}
{"actor":{"display_login":"Trott"}}