doc: update and modernize examples in api docs

[jasnell]

• 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]

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

[jasnell]

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

[MylesBorins]

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

[cjihrig]

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.

[jasnell]

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.

-varhttp=require('http');+consthttp=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]

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

[mscdex]

Argh, the ES6 inline functions continue to creep in!

[jasnell]

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

[cjihrig]

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) => {.

[rvagg]

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)

[chrisdickinson]

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

[rvagg]

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

[chrisdickinson]

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]

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

[jasnell]

@nodejs/documentation

[chrisdickinson]

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

[jasnell]

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]

@jasnell Awesome, thanks — great work!

[Fishrock123]

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

[cjihrig]

LGTM

[MylesBorins]

what change happened here?

[jasnell]

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

[cjihrig]

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

[jasnell]

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]

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

[jasnell]

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

[jasnell]

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

[jasnell]

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]

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

[jasnell]

Rebased and updated...

[jasnell]

Getting this landed momentarily

[jasnell]

Landed in 9b21119