Skip to content

Conversation

vsemozhetbyt
Copy link
Contributor

@vsemozhetbyt vsemozhetbyt commented Apr 7, 2018

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

tools/doc/README.md defines these patterns for module/class properties in the docs:

## module.property
<!-- YAML
added: v0.10.0
-->

* {type}

A description of the property.

### SomeClass.someProperty
<!-- YAML
added: v0.10.0
-->

* {string}

The indication of what `someProperty` is.

Deviations from these patterns prevent our doc-to-JSON tool from proper parsing these sections. In particular, the type field is not added to the property objects, the whole list item being parsed as "short description".

For example: readStream.bytesRead in the fs.json:

{
  "textRaw": "`bytesRead` Value: {number} ",
  "name": "bytesRead",
  "meta": {
    "added": [
      "v6.4.0"
    ],
    "changes": []
  },
  "desc": "<p>The number of bytes that have been read so far.</p>\n",
  "shortDesc": "Value: {number}"
}

Compare: process.debugPort in the process.json:

{
  "textRaw": "`debugPort` {number} ",
  "type": "number",
  "name": "debugPort",
  "meta": {
    "added": [
      "v0.7.2"
    ],
    "changes": []
  },
  "desc": "<p>The port used by Node.js&#39;s debugger when enabled.</p>\n<pre><code class=\"lang-js\">process.debugPort = 5858;\n</code></pre>\n"
}

It seems no useful information is deleted, just the same self-evident word.

Also, I've fixed some other format nits found during the investigation.

@vsemozhetbyt vsemozhetbyt added the fast-track PRs that do not need to wait for 48 hours to land. label Apr 7, 2018
@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 7, 2018
@vsemozhetbyt
Copy link
Contributor Author

@BridgeAR BridgeAR added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 8, 2018
vsemozhetbyt added a commit that referenced this pull request Apr 8, 2018
PR-URL: #19869
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
@vsemozhetbyt
Copy link
Contributor Author

Landed in 08a36a0

@vsemozhetbyt vsemozhetbyt deleted the doc-props branch April 8, 2018 17:40
targos pushed a commit that referenced this pull request Apr 12, 2018
PR-URL: #19869
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations. fast-track PRs that do not need to wait for 48 hours to land.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants