From 324b87b208b80325e71612e7665cd1c1a04ffbbe Mon Sep 17 00:00:00 2001 From: Ram Goli Date: Tue, 12 Dec 2017 23:46:25 +0000 Subject: [PATCH 1/4] doc: change Node.js style to error-first style We change the awkward "Node.js style callback" phrasing to the more informative "error-first style callback," which is more in line with its usage Refs: https://github.com/nodejs/node/pull/17593#discussion_r155963767 --- doc/api/errors.md | 12 ++++++------ doc/api/util.md | 8 ++++---- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index fab75e9bc45fe0..4eb06e323c03a8 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -128,12 +128,12 @@ they are thrown *after* the calling code has already exited. Developers must refer to the documentation for each method to determine exactly how errors raised by those methods are propagated. -### Node.js style callbacks +### Error-first style callbacks Most asynchronous methods exposed by the Node.js core API follow an idiomatic -pattern referred to as a "Node.js style callback". With this pattern, a +pattern referred to as an "error-first style callback". With this pattern, a callback function is passed to the method as an argument. When the operation either completes or an error is raised, the callback function is called with the Error object (if any) passed as the first argument. If no error was raised, @@ -142,7 +142,7 @@ the first argument will be passed as `null`. ```js const fs = require('fs'); -function nodeStyleCallback(err, data) { +function errorFirstStyleCallback(err, data) { if (err) { console.error('There was an error', err); return; @@ -150,13 +150,13 @@ function nodeStyleCallback(err, data) { console.log(data); } -fs.readFile('/some/file/that/does-not-exist', nodeStyleCallback); -fs.readFile('/some/file/that/does-exist', nodeStyleCallback); +fs.readFile('/some/file/that/does-not-exist', errorFirstStyleCallback); +fs.readFile('/some/file/that/does-exist', errorFirstStyleCallback); ``` The JavaScript `try / catch` mechanism **cannot** be used to intercept errors generated by asynchronous APIs. A common mistake for beginners is to try to -use `throw` inside a Node.js style callback: +use `throw` inside an error-first style callback: ```js // THIS WILL NOT WORK: diff --git a/doc/api/util.md b/doc/api/util.md index 8e3befcebf6ec2..4ebc0a3a8ad6c9 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -517,7 +517,7 @@ added: v8.0.0 * `original` {Function} * Returns: {Function} -Takes a function following the common Node.js callback style, i.e. taking a +Takes a function following the common error-first style callback, i.e. taking a `(err, value) => ...` callback as the last argument, and returns a version that returns promises. @@ -554,9 +554,9 @@ will return its value, see [Custom promisified functions][]. `promisify()` assumes that `original` is a function taking a callback as its final argument in all cases. If `original` is not a function, `promisify()` -will throw an error. If `original` is a function but its last argument is not a -Node.js style callback, it will still be passed a Node.js style callback -as its last argument. +will throw an error. If `original` is a function but its last argument is not +an error-first style callback, it will still be passed an error-first style +callback as its last argument. ### Custom promisified functions From 5fc61ad1a1d33de85c0d5d8449a28e78ba34e262 Mon Sep 17 00:00:00 2001 From: Ram Goli Date: Wed, 13 Dec 2017 01:27:04 +0000 Subject: [PATCH 2/4] doc: remove style, update callbackify --- doc/api/errors.md | 6 +++--- doc/api/util.md | 13 +++++++------ 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 4eb06e323c03a8..45efc476b36709 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -128,12 +128,12 @@ they are thrown *after* the calling code has already exited. Developers must refer to the documentation for each method to determine exactly how errors raised by those methods are propagated. -### Error-first style callbacks +### Error-first callbacks Most asynchronous methods exposed by the Node.js core API follow an idiomatic -pattern referred to as an "error-first style callback". With this pattern, a +pattern referred to as an _error-first callback_. With this pattern, a callback function is passed to the method as an argument. When the operation either completes or an error is raised, the callback function is called with the Error object (if any) passed as the first argument. If no error was raised, @@ -156,7 +156,7 @@ fs.readFile('/some/file/that/does-exist', errorFirstStyleCallback); The JavaScript `try / catch` mechanism **cannot** be used to intercept errors generated by asynchronous APIs. A common mistake for beginners is to try to -use `throw` inside an error-first style callback: +use `throw` inside an error-first callback: ```js // THIS WILL NOT WORK: diff --git a/doc/api/util.md b/doc/api/util.md index 4ebc0a3a8ad6c9..43e149314ea2b0 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -21,9 +21,10 @@ added: v8.2.0 * Returns: {Function} a callback style function Takes an `async` function (or a function that returns a Promise) and returns a -function following the Node.js error first callback style. In the callback, the -first argument will be the rejection reason (or `null` if the Promise resolved), -and the second argument will be the resolved value. +function following the error-first callback style, i.e. taking +a `(err, value) => ...` callback as the last argument. In the callback, the +first argument will be the rejection reason (or `null` if the Promise +resolved), and the second argument will be the resolved value. For example: @@ -517,8 +518,8 @@ added: v8.0.0 * `original` {Function} * Returns: {Function} -Takes a function following the common error-first style callback, i.e. taking a -`(err, value) => ...` callback as the last argument, and returns a version +Takes a function following the common error-first callback style, i.e. taking +a `(err, value) => ...` callback as the last argument, and returns a version that returns promises. For example: @@ -555,7 +556,7 @@ will return its value, see [Custom promisified functions][]. `promisify()` assumes that `original` is a function taking a callback as its final argument in all cases. If `original` is not a function, `promisify()` will throw an error. If `original` is a function but its last argument is not -an error-first style callback, it will still be passed an error-first style +an error-first callback, it will still be passed an error-first callback as its last argument. ### Custom promisified functions From 1f288e1cf78d107d1a6413eb0721223be231cfe0 Mon Sep 17 00:00:00 2001 From: Ram Goli Date: Wed, 13 Dec 2017 01:37:53 +0000 Subject: [PATCH 3/4] doc: remove style from errors.md --- doc/api/errors.md | 6 +++--- doc/api/util.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 45efc476b36709..9ef89b1090f27c 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -142,7 +142,7 @@ the first argument will be passed as `null`. ```js const fs = require('fs'); -function errorFirstStyleCallback(err, data) { +function errorFirstCallback(err, data) { if (err) { console.error('There was an error', err); return; @@ -150,8 +150,8 @@ function errorFirstStyleCallback(err, data) { console.log(data); } -fs.readFile('/some/file/that/does-not-exist', errorFirstStyleCallback); -fs.readFile('/some/file/that/does-exist', errorFirstStyleCallback); +fs.readFile('/some/file/that/does-not-exist', errorFirstCallback); +fs.readFile('/some/file/that/does-exist', errorFirstCallback); ``` The JavaScript `try / catch` mechanism **cannot** be used to intercept errors diff --git a/doc/api/util.md b/doc/api/util.md index 43e149314ea2b0..a88413a65a5bde 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -555,7 +555,7 @@ will return its value, see [Custom promisified functions][]. `promisify()` assumes that `original` is a function taking a callback as its final argument in all cases. If `original` is not a function, `promisify()` -will throw an error. If `original` is a function but its last argument is not +will throw an error. If `original` is a function but its last argument is not an error-first callback, it will still be passed an error-first callback as its last argument. From 9f13040eabd4ec8493a30c6cfd6a76cc2af9603d Mon Sep 17 00:00:00 2001 From: Ram Goli Date: Wed, 13 Dec 2017 18:56:13 +0000 Subject: [PATCH 4/4] doc: retain old phrasing --- doc/api/errors.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 9ef89b1090f27c..776639d2e4cb3f 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -133,11 +133,12 @@ exactly how errors raised by those methods are propagated. Most asynchronous methods exposed by the Node.js core API follow an idiomatic -pattern referred to as an _error-first callback_. With this pattern, a -callback function is passed to the method as an argument. When the operation -either completes or an error is raised, the callback function is called with -the Error object (if any) passed as the first argument. If no error was raised, -the first argument will be passed as `null`. +pattern referred to as an _error-first callback_ (sometimes referred to as +a _Node.js style callback_). With this pattern, a callback function is passed +to the method as an argument. When the operation either completes or an error +is raised, the callback function is called with +the Error object (if any) passed as the first argument. If no error was +raised, the first argument will be passed as `null`. ```js const fs = require('fs');