Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: unify property sections #19869

Closed
wants to merge 1 commit into from
Closed

doc: unify property sections #19869

wants to merge 1 commit into from

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 <trivikr.dev@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
@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 <trivikr.dev@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
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