doc: standardize function param/object prop style #13769

gibfahn · 2017-06-18T19:55:49Z

Checklist

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

Affected core subsystem(s)

doc

Probably should have a lint rule once #12756 lands.

vsemozhetbyt · 2017-06-18T20:06:24Z

doc/STYLE_GUIDE.md

@@ -65,6 +65,9 @@
  * Make the "Note:" label italic, i.e. `*Note*:`.
  * Use a capital letter after the "Note:" label.
  * Preferably, make the note a new paragraph for better visual distinction.
+* Function arguments or object properties should use the following format:
+  * <code>* `name` {type|type2} Optional description. **Default:** `defaultValue`</code>


Should this be rendered or should we escape the special symbols to make them visible? Currently, this is rendered.

Maybe we could escape this and not escape the example, WDYT (see update)?

vsemozhetbyt · 2017-06-18T20:35:21Z

Should we add something about type links to MDN?

cjihrig

LGTM with a few comments.

cjihrig · 2017-06-18T21:22:30Z

doc/api/async_hooks.md

+* `type` {string} The type of the async resource.
+* `triggerAsyncId` {number} The unique ID of the async resource in whose
+  execution context this async resource was created.
+* `resource` {Object} Reference to the resource representing the async operation,`


Is the backtick at the end of the line intentional?

cjihrig · 2017-06-18T21:22:51Z

doc/api/async_hooks.md

-* arguments
-  * `type` {string} the type of ascyc event
-  * `triggerAsyncId` {number} the ID of the execution context that created this async
+* `type` {string} The type of ascyc event.


Not related to this PR, but ascyc is spelled wrong.

cjihrig · 2017-06-18T21:24:08Z

doc/api/buffer.md

-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - byteLength`
-* `byteLength` {integer} How many bytes to read. Must satisfy: `0 < byteLength <= 6`
-* `noAssert` {boolean} Skip `offset` and `byteLength` validation? **Default:** `false`
+* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - byteLength`.


I'm not sure if it should be addressed in this PR, but there are lines longer than 80 characters.

Sounds like something for #12756

cjihrig · 2017-06-18T21:25:23Z

doc/api/buffer.md

@@ -1819,8 +1819,8 @@ console.log(buf.readUInt32LE(1).toString(16));
 added: v0.11.15
 -->

-* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - byteLength`
-* `byteLength` {integer} How many bytes to read. Must satisfy: `0 < byteLength <= 6`
+* `offset` {integer} Where to start reading. Must satisfy: `0 <= offset <= buf.length - byteLength`.


Also not related to this PR, but "where to start reading" and "how many bytes to read" could probably be rewritten to sound less like questions.

I did
Where to start reading -> Number of bytes in at which to start reading. and
How many bytes -> Number of bytes

Let me know if you'd prefer something else.

I'd go with Position to begin reading and Number of bytes to read

gibfahn · 2017-06-18T21:35:12Z

Thanks for the comments @cjihrig. If this seems reasonable I might as well fix up the rest of the docs then.

Refs: nodejs#13769 New style is introduced in PR nodejs#13769.

gibfahn · 2017-06-20T15:19:17Z

Comment from @jasnell in #13767 (comment)

It's good to get consistency here but I would prefer something like:
Defaults to `fs.constants.F_OK`
Without the bold styling.

PR-URL: #13767 Refs: #11135 Refs: #13769 Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

PR-URL: nodejs#13767 Refs: nodejs#11135 Refs: nodejs#13769 Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

PR-URL: #13767 Refs: #11135 Refs: #13769 Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

gibfahn · 2017-08-13T00:12:49Z

Looks like this fell through the cracks, rebased. I'll land this tomorrow unless there are any objections.

gibfahn · 2017-09-26T22:59:46Z

CI: https://ci.nodejs.org/job/node-test-commit/12627/

BridgeAR · 2017-09-28T05:28:32Z

Landed in 1175c9d

PR-URL: #13769 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

MylesBorins · 2017-09-28T06:54:42Z

This is not landing cleanly on 8.x, could it be backported?

PR-URL: nodejs#13769 Backport-PR-URL: nodejs#15687 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

gibfahn · 2017-09-29T17:37:20Z

@MylesBorins #15687

PR-URL: #13769 Backport-PR-URL: #15687 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

PR-URL: nodejs/node#13769 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

PR-URL: #13769 Backport-PR-URL: #15687 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

MylesBorins · 2017-10-17T19:13:25Z

This does not land cleanly in LTS. Please feel free to manually backport by following the guide. Please also feel free to replace do-not-land if it is being backported

PR-URL: nodejs#13769 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

matejkrajcovic · 2017-10-27T18:08:17Z

@MylesBorins backported in #16560.

Backport-PR-URL: #16560 PR-URL: #13769 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Jun 18, 2017

gibfahn force-pushed the default-doc branch from ee77ffc to 44de349 Compare June 18, 2017 19:56

gibfahn mentioned this pull request Jun 18, 2017

doc: add default values to function signatures in fs.md #13767

Closed

2 tasks

vsemozhetbyt reviewed Jun 18, 2017

View reviewed changes

gibfahn force-pushed the default-doc branch 2 times, most recently from 897b8d1 to e033f38 Compare June 18, 2017 20:22

vsemozhetbyt approved these changes Jun 18, 2017

View reviewed changes

gibfahn force-pushed the default-doc branch 4 times, most recently from d8d7a84 to 9f828c0 Compare June 18, 2017 21:19

cjihrig approved these changes Jun 18, 2017

View reviewed changes

gibfahn force-pushed the default-doc branch from 9f828c0 to 2a3260e Compare June 18, 2017 21:32

gibfahn added the wip Issues and PRs that are still a work in progress. label Jun 18, 2017

gibfahn force-pushed the default-doc branch 2 times, most recently from 218e9ae to bd7efb5 Compare June 18, 2017 22:06

jasnell approved these changes Jun 19, 2017

View reviewed changes

matejkrajcovic added a commit to matejkrajcovic/node that referenced this pull request Jun 19, 2017

doc: update fs.md to new default values style

0cfdbde

Refs: nodejs#13769 New style is introduced in PR nodejs#13769.

mhdawson approved these changes Jun 20, 2017

View reviewed changes

tniessen pushed a commit that referenced this pull request Jul 2, 2017

doc: add default values to functions in fs.md

51bb4ac

PR-URL: #13767 Refs: #11135 Refs: #13769 Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

addaleax pushed a commit that referenced this pull request Jul 11, 2017

doc: add default values to functions in fs.md

e37866c

PR-URL: #13767 Refs: #11135 Refs: #13769 Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

addaleax pushed a commit that referenced this pull request Jul 18, 2017

doc: add default values to functions in fs.md

310040c

PR-URL: #13767 Refs: #11135 Refs: #13769 Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Fishrock123 pushed a commit that referenced this pull request Jul 19, 2017

doc: add default values to functions in fs.md

ee5ed6e

PR-URL: #13767 Refs: #11135 Refs: #13769 Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

gibfahn force-pushed the default-doc branch from bd7efb5 to e2f1123 Compare August 13, 2017 00:10

gibfahn mentioned this pull request Aug 13, 2017

Suggestion: Return type in function declaration & possible option to view types by clicking in doc #14624

Closed

BridgeAR closed this Sep 28, 2017

MylesBorins added the backport-requested-v8.x label Sep 28, 2017

gibfahn deleted the default-doc branch September 29, 2017 17:34

gibfahn mentioned this pull request Sep 29, 2017

[v8.x] doc: standardize function param/object prop style #15687

Closed

MylesBorins added backported-to-v8.x and removed backport-requested-v8.x labels Sep 29, 2017

MylesBorins mentioned this pull request Oct 3, 2017

v8.7.0 proposal #15762

Merged

MylesBorins added the dont-land-on-v6.x label Oct 17, 2017

matejkrajcovic mentioned this pull request Oct 27, 2017

[v6.x backport] doc: standardize function param/object prop style #16560

Closed

2 tasks

This was referenced Nov 3, 2017

v4.8.6 proposal #16500

Merged

v6.12.0 proposal #16263

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: standardize function param/object prop style #13769

doc: standardize function param/object prop style #13769

gibfahn commented Jun 18, 2017 •

edited

Loading

vsemozhetbyt Jun 18, 2017 •

edited

Loading

gibfahn Jun 18, 2017 •

edited

Loading

vsemozhetbyt commented Jun 18, 2017

cjihrig left a comment

cjihrig Jun 18, 2017

cjihrig Jun 18, 2017

cjihrig Jun 18, 2017

gibfahn Jun 18, 2017

cjihrig Jun 18, 2017

gibfahn Jun 18, 2017

cjihrig Jun 18, 2017

gibfahn commented Jun 18, 2017

gibfahn commented Jun 20, 2017

gibfahn commented Aug 13, 2017

gibfahn commented Sep 26, 2017

BridgeAR commented Sep 28, 2017

MylesBorins commented Sep 28, 2017

gibfahn commented Sep 29, 2017

MylesBorins commented Oct 17, 2017

matejkrajcovic commented Oct 27, 2017

doc: standardize function param/object prop style #13769

doc: standardize function param/object prop style #13769

Conversation

gibfahn commented Jun 18, 2017 • edited Loading

Checklist

Affected core subsystem(s)

vsemozhetbyt Jun 18, 2017 • edited Loading

Choose a reason for hiding this comment

gibfahn Jun 18, 2017 • edited Loading

Choose a reason for hiding this comment

vsemozhetbyt commented Jun 18, 2017

cjihrig left a comment

Choose a reason for hiding this comment

cjihrig Jun 18, 2017

Choose a reason for hiding this comment

cjihrig Jun 18, 2017

Choose a reason for hiding this comment

cjihrig Jun 18, 2017

Choose a reason for hiding this comment

gibfahn Jun 18, 2017

Choose a reason for hiding this comment

cjihrig Jun 18, 2017

Choose a reason for hiding this comment

gibfahn Jun 18, 2017

Choose a reason for hiding this comment

cjihrig Jun 18, 2017

Choose a reason for hiding this comment

gibfahn commented Jun 18, 2017

gibfahn commented Jun 20, 2017

gibfahn commented Aug 13, 2017

gibfahn commented Sep 26, 2017

BridgeAR commented Sep 28, 2017

MylesBorins commented Sep 28, 2017

gibfahn commented Sep 29, 2017

MylesBorins commented Oct 17, 2017

matejkrajcovic commented Oct 27, 2017

gibfahn commented Jun 18, 2017 •

edited

Loading

vsemozhetbyt Jun 18, 2017 •

edited

Loading

gibfahn Jun 18, 2017 •

edited

Loading