doc: update and modernize examples in api docs #4282

jasnell · 2015-12-14T23:28:41Z

Use single quotes consistently
Modernize examples to use template strings and arrow funcs
Fix typos
Fix a few line wrap issues

/cc @nodejs/http

MylesBorins · 2015-12-14T23:30:23Z

doc/api/http.markdown

@@ -103,7 +103,7 @@ of these values set to their respective defaults.
 To configure any of them, you must create your own [`http.Agent`][] object.

 ```javascript
-var http = require('http');
+const http = require('http');


should we do a pass at replacing all instances of require in docs with const?

Incrementally, perhaps. I don't think it's critical enough to do all at once

fair enough. my only thought on this is that it might be weird to have things in the docs inconsistent, but it makes sense to avoid massive churn

It might actually be better to have huge docs only churn in a single commit, instead of 32 commits. People are a lot less likely to bisect and blame the docs.

Looking it over, I agree. It's not a huge chunk of work. Already have it
mostly done. Will update this PR with the other updates.
On Dec 14, 2015 4:51 PM, "Colin Ihrig" notifications@github.com wrote:

In doc/api/http.markdown
#4282 (comment):

@@ -103,7 +103,7 @@ of these values set to their respective defaults.
To configure any of them, you must create your own [http.Agent][] object.

-var http = require('http'); +const http = require('http');

It might actually be better to have huge docs only churn in a single
commit, instead of 32 commits #3662.
People are a lot less likely to bisect and blame the docs.

—
Reply to this email directly or view it on GitHub
https://github.com/nodejs/node/pull/4282/files#r47583137.

MylesBorins · 2015-12-14T23:33:40Z

LGTM. Small comment regarding using const in docs above, but that is not relevant to this landing

mscdex · 2015-12-14T23:58:51Z

Argh, the ES6 inline functions continue to creep in!

jasnell · 2015-12-15T00:02:38Z

lol ... they're not the prettiest thing in the world but it's the direction things are heading

cjihrig · 2015-12-15T00:54:43Z

doc/api/http.markdown

@@ -64,10 +64,10 @@ a `'close'` event or a special `'agentRemove'` event. This means that if
 you intend to keep one HTTP request open for a long time and don't
 want it to stay in the pool you can do something along the lines of:

-    http.get(options, function(res) {
+    http.get(options, (res)=> {


I don't think we have any linting rules for arrow functions yet, but from a quick code search, it looks like the convention has been to put spaces on each side of the arrow. So, in this case (res) => {.

agreed, I'm only seeing (args) => { in use in the wild at the moment with the extra space (not that I'm looking very widely)

In this case it's probably fine to omit the parens, as well — http.get(options, res => {

my vote would be to never omit parens to be explicit what's going on, I personally find the paren-free version little too terse

It's definitely a brand new 🚲🏡; I don't feel strongly enough either way to propose setting a hard-and-fast rule for it. In my own projects, I lean towards minimizing characters in code examples to give other info more room, but two characters is not a huge amount of savings so I'm comfortable leaving this as a personal preference of the doc author for the time being.

jasnell · 2015-12-15T03:39:01Z

@thealphanerd @cjihrig ... ok, just pushed a big update. Fixed up all of the doc examples at once.

jasnell · 2015-12-15T03:41:17Z

@nodejs/documentation

chrisdickinson · 2015-12-15T05:44:44Z

Are you comfortable asserting that the code examples still work as authored? If so, this LGTM pending arrow function style nits!

jasnell · 2015-12-15T05:49:26Z

I'm going to be going through and testing the various cases. Gimme a day to
get through them. Pretty certain everything is good tho
On Dec 14, 2015 9:44 PM, "Chris Dickinson" notifications@github.com wrote:

Are you comfortable asserting that the code examples still work as
authored? If so, this LGTM pending arrow function style nits!

—
Reply to this email directly or view it on GitHub
#4282 (comment).

chrisdickinson · 2015-12-15T05:50:48Z

@jasnell Awesome, thanks — great work!

Fishrock123 · 2015-12-15T16:02:11Z

While we're at it, is there a good reason to keep semicolons in these?

cjihrig · 2015-12-15T16:08:43Z

LGTM

MylesBorins · 2015-12-15T16:11:13Z

doc/api/assert.markdown

@@ -135,4 +135,4 @@ Custom error validation:
 [`assert.throws()`]: #assert_assert_throws_block_error_message
 [`Error`]: errors.html#errors_class_error
 [`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
-[`TypeError`]: errors.html#errors_class_typeerror


what change happened here?

Not a clue. Likely a whitespace change. Will fix.

cjihrig · 2015-12-15T23:09:12Z

New changes look good. Left one comment directly on the commit instead of the PR.

jasnell · 2015-12-16T03:01:30Z

const can be used without 'use strict', it's let that can't be used without it.

bash-3.2$ cat ~/tmp/test.js
const m = 1;
let n = 1;
bash-3.2$ node ~/tmp.test
module.js:339
    throw err;
    ^

Error: Cannot find module '/Users/james/tmp.test'
    at Function.Module._resolveFilename (module.js:337:15)
    at Function.Module._load (module.js:287:25)
    at Function.Module.runMain (module.js:467:10)
    at startup (node.js:134:18)
    at node.js:961:3
bash-3.2$

Trott · 2015-12-16T03:01:46Z

Uh, yeah, never mind my previous comments about strict mode...

jasnell · 2015-12-16T03:05:01Z

Pushed update to pull the "fix" for #4296 back out. That change isn't necessary for master or v5

jasnell · 2015-12-16T03:09:47Z

@cjihrig ... updated the 0022 to 0o022 per your suggestion

jasnell · 2015-12-16T03:11:19Z

I marked this for LTS watch but it likely won't land cleanly. If/when it lands, I'll put together a modified version for v4.x-staging

jasnell · 2015-12-16T16:32:00Z

I'd like to get this landed soon but would appreciate a bit more eyes on it. /cc @nodejs/documentation

jasnell · 2015-12-16T16:45:28Z

Rebased and updated...

* Use single quotes consistently * Modernize examples to use template strings and arrow funcs * Fix a few typos

Additional example edits for consistency

@cjihrig

Per @cjihrig's suggestion

jasnell · 2015-12-17T16:04:01Z

Getting this landed momentarily

* Use single quotes consistently * Modernize examples to use template strings and arrow funcs * Fix a few typos * Example edits for consistency PR-URL: #4282 Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

jasnell · 2015-12-17T16:08:23Z

Landed in 9b21119

* Use single quotes consistently * Modernize examples to use template strings and arrow funcs * Fix a few typos * Example edits for consistency PR-URL: nodejs#4282 Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

* Use single quotes consistently * Modernize examples to use template strings and arrow funcs * Fix a few typos * Example edits for consistency PR-URL: #4282 Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

* Use single quotes consistently * Modernize examples to use template strings and arrow funcs * Fix a few typos * Example edits for consistency PR-URL: nodejs#4282 Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

* Use single quotes consistently * Modernize examples to use template strings and arrow funcs * Fix a few typos * Example edits for consistency PR-URL: #4282 Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

* Use single quotes consistently * Modernize examples to use template strings and arrow funcs * Fix a few typos * Example edits for consistency PR-URL: nodejs#4282 Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

jasnell added http Issues or PRs related to the http subsystem. doc Issues and PRs related to the documentations. labels Dec 14, 2015

MylesBorins reviewed Dec 14, 2015
View reviewed changes

cjihrig reviewed Dec 15, 2015
View reviewed changes

jasnell force-pushed the fix-http-doc branch from b1aaf1e to 49414c1 Compare December 15, 2015 03:38

jasnell changed the title ~~doc: update examples in http.markdown~~ doc: update and modernize examples in api docs Dec 15, 2015

MylesBorins reviewed Dec 15, 2015
View reviewed changes

jasnell added the lts-watch-v4.x label Dec 15, 2015

jasnell force-pushed the fix-http-doc branch from 184623b to 6912a17 Compare December 16, 2015 03:03

jasnell force-pushed the fix-http-doc branch from 0961cf3 to 866efa0 Compare December 16, 2015 16:45

jasnell added 3 commits December 17, 2015 08:02

doc: fix, modernize examples in docs

f950904

* Use single quotes consistently * Modernize examples to use template strings and arrow funcs * Fix a few typos

doc: additional example edits

bae6728

Additional example edits for consistency

doc: update 0022 to 0o022 in process.markdown

aab18d0

Per @cjihrig's suggestion

jasnell force-pushed the fix-http-doc branch from 866efa0 to aab18d0 Compare December 17, 2015 16:03

jasnell closed this Dec 17, 2015

jasnell mentioned this pull request Dec 17, 2015

Release 4.2.4 Planning #4321

Closed

MylesBorins added land-on-v4.x and removed lts-watch-v4.x labels Dec 30, 2015

MylesBorins mentioned this pull request Jan 19, 2016

V4.2.5 proposal #4768

Merged

ChALkeR mentioned this pull request Jan 24, 2016

doc: refactor function expressions to arrow functions #4832

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: update and modernize examples in api docs #4282

doc: update and modernize examples in api docs #4282

jasnell commented Dec 14, 2015

MylesBorins Dec 14, 2015

jasnell Dec 14, 2015

MylesBorins Dec 14, 2015

cjihrig Dec 15, 2015

jasnell Dec 15, 2015

MylesBorins commented Dec 14, 2015

mscdex commented Dec 14, 2015

jasnell commented Dec 15, 2015

cjihrig Dec 15, 2015

rvagg Dec 15, 2015

chrisdickinson Dec 15, 2015

rvagg Dec 15, 2015

chrisdickinson Dec 15, 2015

jasnell commented Dec 15, 2015

jasnell commented Dec 15, 2015

chrisdickinson commented Dec 15, 2015

jasnell commented Dec 15, 2015

chrisdickinson commented Dec 15, 2015

Fishrock123 commented Dec 15, 2015

cjihrig commented Dec 15, 2015

MylesBorins Dec 15, 2015

jasnell Dec 15, 2015

cjihrig commented Dec 15, 2015

jasnell commented Dec 16, 2015

Trott commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 17, 2015

jasnell commented Dec 17, 2015

doc: update and modernize examples in api docs #4282

doc: update and modernize examples in api docs #4282

Conversation

jasnell commented Dec 14, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MylesBorins commented Dec 14, 2015

mscdex commented Dec 14, 2015

jasnell commented Dec 15, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Dec 15, 2015

jasnell commented Dec 15, 2015

chrisdickinson commented Dec 15, 2015

jasnell commented Dec 15, 2015

chrisdickinson commented Dec 15, 2015

Fishrock123 commented Dec 15, 2015

cjihrig commented Dec 15, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cjihrig commented Dec 15, 2015

jasnell commented Dec 16, 2015

Trott commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 16, 2015

jasnell commented Dec 17, 2015

jasnell commented Dec 17, 2015