Skip to content

doc: unify property sections

Rodrigo Muino Tomonari requested to merge github/fork/vsemozhetbyt/doc-props into master
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.

Merge request reports