doc: add and fix System Error properties #10986

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
9 participants
@darai0512
Contributor

darai0512 commented Jan 25, 2017

Checklist
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc

Description of change

In System Errors properties of Errors API, error.path, error.address and error.port are not described although being also represented as augmented Error objects with added properties by the following code.

properties link
address, port https://github.com/nodejs/node/blob/v6.x-staging/lib/util.js#L1030-L1051
path https://github.com/nodejs/node/blob/master/lib/child_process.js#L526
// examples
// with `path` property
$node -e "require('fs').readFile('a file that does not exist', (err, data) => { console.error(err); });"
{ Error: ENOENT: no such file or directory, open 'a file that does not exist'
    at Error (native)
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: 'a file that does not exist' }

// with `address` and `port` property
$node -e "require('net').connect({port: 100}).on('error', (err) => { console.error(err); });"
{ Error: connect ECONNREFUSED 127.0.0.1:100
    at Object.exports._errnoException (util.js:1022:11)
    at exports._exceptionWithHostPort (util.js:1045:20)
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1087:14)
  code: 'ECONNREFUSED',
  errno: 'ECONNREFUSED',
  syscall: 'connect',
  address: '127.0.0.1',
  port: 100 }

// with `address` property (without `port` property)
$node -e "require('net').connect({host: 'localhost'}).on('error', (err) => { console.error(err); });"
{ Error: connect EADDRNOTAVAIL 127.0.0.1 - Local (0.0.0.0:54881)
    at Object.exports._errnoException (util.js:1022:11)
    at exports._exceptionWithHostPort (util.js:1045:20)
    at connect (net.js:881:16)
    at net.js:1010:7
    at GetAddrInfoReqWrap.asyncCallback [as callback] (dns.js:62:16)
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:81:10)
  code: 'EADDRNOTAVAIL',
  errno: 'EADDRNOTAVAIL',
  syscall: 'connect',
  address: '127.0.0.1' }

Also, error.errno doesn't always return a number like the above examples.
Please check the following code.

https://github.com/nodejs/node/blob/v6.x-staging/lib/util.js#L1024

doc/api/errors.md
@@ -459,10 +459,27 @@ Returns a number corresponding to the **negated** error code, which may be
referenced in `man 2 intro`. For example, an `ENOENT` error has an `errno` of
`-2` because the error code for `ENOENT` is `2`.
+In some mudules, returns the same string as `error.code`.

This comment has been minimized.

@mscdex

mscdex Jan 25, 2017

Contributor

s/mudules/modules/

@mscdex

mscdex Jan 25, 2017

Contributor

s/mudules/modules/

This comment has been minimized.

@darai0512

darai0512 Jan 25, 2017

Contributor

@mscdex Thanks for your review.

@darai0512

darai0512 Jan 25, 2017

Contributor

@mscdex Thanks for your review.

doc/api/errors.md
#### error.syscall
Returns a string describing the [syscall][] that failed.
+#### error.path
+
+Returns a string of the specified invalid pathname in case of using some modules

This comment has been minimized.

@mscdex

mscdex Jan 25, 2017

Contributor

Despite the term 'returns' being better suited for functions rather than properties, this would still be better wording IMHO: 'Returns a string containing the relevant invalid pathname (where applicable).'

Similarly for the other properties added below.

@mscdex

mscdex Jan 25, 2017

Contributor

Despite the term 'returns' being better suited for functions rather than properties, this would still be better wording IMHO: 'Returns a string containing the relevant invalid pathname (where applicable).'

Similarly for the other properties added below.

This comment has been minimized.

@Trott

Trott Jan 25, 2017

Member

Even though there are existing contrary examples in this very file, I think we should avoid saying returns when talking about a property. We should reserve returns for functions.

So, instead of Returns a string that..., just A string that.... Yes, it will technically be a sentence fragment, but I think it's acceptable in this case. It would certainly be clear and understandable which is the most important thing.

/cc @nodejs/documentation

@Trott

Trott Jan 25, 2017

Member

Even though there are existing contrary examples in this very file, I think we should avoid saying returns when talking about a property. We should reserve returns for functions.

So, instead of Returns a string that..., just A string that.... Yes, it will technically be a sentence fragment, but I think it's acceptable in this case. It would certainly be clear and understandable which is the most important thing.

/cc @nodejs/documentation

This comment has been minimized.

@Qard

Qard Jan 25, 2017

Member

I feel like a simple s/returns/is/ would make sense, in most cases.

@Qard

Qard Jan 25, 2017

Member

I feel like a simple s/returns/is/ would make sense, in most cases.

This comment has been minimized.

@darai0512

darai0512 Jan 25, 2017

Contributor

@mscdex @Trott @Qard Thanks for your review.
I did s/Returns/Is/ about this page's properties.

@darai0512

darai0512 Jan 25, 2017

Contributor

@mscdex @Trott @Qard Thanks for your review.
I did s/Returns/Is/ about this page's properties.

This comment has been minimized.

@Trott

Trott Jan 25, 2017

Member

Hate to disagree with @Qard, but -1 on this approach. We don't start descriptions with Is anywhere else in the docs. Let's not create a third way to do things. Let's standardize on one of the existing approaches.

IMO, this should be: A string of the specified invalid pathname in case of using some modules... rather than Is a string of the specified...

@Trott

Trott Jan 25, 2017

Member

Hate to disagree with @Qard, but -1 on this approach. We don't start descriptions with Is anywhere else in the docs. Let's not create a third way to do things. Let's standardize on one of the existing approaches.

IMO, this should be: A string of the specified invalid pathname in case of using some modules... rather than Is a string of the specified...

This comment has been minimized.

@Qard

Qard Jan 25, 2017

Member

I'm good either way. Just figured "is" might provide a better hint as to the access method.

@Qard

Qard Jan 25, 2017

Member

I'm good either way. Just figured "is" might provide a better hint as to the access method.

@darai0512

This comment has been minimized.

Show comment
Hide comment
@darai0512

darai0512 Jan 25, 2017

Contributor

About the following expression as well, not 'returns' but 'is' may be better.
https://github.com/nodejs/node/blame/master/doc/api/errors.md#L208
But I think it is natural enough.

Contributor

darai0512 commented Jan 25, 2017

About the following expression as well, not 'returns' but 'is' may be better.
https://github.com/nodejs/node/blame/master/doc/api/errors.md#L208
But I think it is natural enough.

doc/api/errors.md
referenced in `man 2 intro`. For example, an `ENOENT` error has an `errno` of
`-2` because the error code for `ENOENT` is `2`.
+In some modules, this property is the same string as `error.code`.

This comment has been minimized.

@mscdex

mscdex Jan 25, 2017

Contributor

'Same string?' Above it is mentioned that this is a number, not a string.

@mscdex

mscdex Jan 25, 2017

Contributor

'Same string?' Above it is mentioned that this is a number, not a string.

doc/api/errors.md
+
+#### error.path
+
+Is a string of the specified invalid pathname in case of using some modules

This comment has been minimized.

@mscdex

mscdex Jan 25, 2017

Contributor

'the specified' here is confusing. It makes it sound like it's a value the user is passing into a function or something. As previously suggested, I would use something like:

Is a string containing a relevant invalid path name (where applicable). Some modules that include this property are fs and child_process.

and structuring the other two property descriptions similarly.

@mscdex

mscdex Jan 25, 2017

Contributor

'the specified' here is confusing. It makes it sound like it's a value the user is passing into a function or something. As previously suggested, I would use something like:

Is a string containing a relevant invalid path name (where applicable). Some modules that include this property are fs and child_process.

and structuring the other two property descriptions similarly.

This comment has been minimized.

@darai0512

darai0512 Jan 27, 2017

Contributor

@mscdex
I understood. I will fix.

@darai0512

darai0512 Jan 27, 2017

Contributor

@mscdex
I understood. I will fix.

doc/api/errors.md
referenced in `man 2 intro`. For example, an `ENOENT` error has an `errno` of
`-2` because the error code for `ENOENT` is `2`.
+In some modules, this property is the same string as `error.code`.

This comment has been minimized.

@sam-github

sam-github Jan 25, 2017

Member

I know, its miserable trying to figure exactly which modules do this, but this doc reads as "behaviour is random, shrug". Consider giving some advice on what to do:

const errno = error.errno || error.code;
@sam-github

sam-github Jan 25, 2017

Member

I know, its miserable trying to figure exactly which modules do this, but this doc reads as "behaviour is random, shrug". Consider giving some advice on what to do:

const errno = error.errno || error.code;

This comment has been minimized.

@mscdex

mscdex Jan 25, 2017

Contributor

That may not be preferrable if errno is a number, whereas code is a string? You'd have to explicitly cast to a string.

@mscdex

mscdex Jan 25, 2017

Contributor

That may not be preferrable if errno is a number, whereas code is a string? You'd have to explicitly cast to a string.

This comment has been minimized.

@sam-github

sam-github Jan 25, 2017

Member

OK, then the docs should say "In some modules, is a number corresponding to ...etc." because the first sentence is being contradicted by the paragraph after ATM.

Is there an open issue to track this? It doesn't strike me as so helpful to sometimes be an "E" string, and sometimes a number.

@sam-github

sam-github Jan 25, 2017

Member

OK, then the docs should say "In some modules, is a number corresponding to ...etc." because the first sentence is being contradicted by the paragraph after ATM.

Is there an open issue to track this? It doesn't strike me as so helpful to sometimes be an "E" string, and sometimes a number.

This comment has been minimized.

@mscdex

mscdex Jan 25, 2017

Contributor

I'm not familiar enough with the libuv error codes, but I would guess that the .code would be the same across platforms whereas the .errno may not be?

@mscdex

mscdex Jan 25, 2017

Contributor

I'm not familiar enough with the libuv error codes, but I would guess that the .code would be the same across platforms whereas the .errno may not be?

This comment has been minimized.

@shigeki

shigeki Jan 26, 2017

Contributor

I heard this from @darai0512 a few days ago and also was surprised to know that.
I think we cannot change them for there are codes expecting errno is string.

@shigeki

shigeki Jan 26, 2017

Contributor

I heard this from @darai0512 a few days ago and also was surprised to know that.
I think we cannot change them for there are codes expecting errno is string.

This comment has been minimized.

@shigeki

shigeki Jan 26, 2017

Contributor

I think it is better to fix like this. How is it?

--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -455,9 +455,11 @@ a sequence of capital letters, and may be referenced in `man 2 intro`.

 #### error.errno

-Returns a number corresponding to the **negated** error code, which may be
-referenced in `man 2 intro`. For example, an `ENOENT` error has an `errno` of
-`-2` because the error code for `ENOENT` is `2`.
+Returns a number or a string. The number corresponds to the
+**negated** error code, which may be referenced in `man 2 intro`. For
+example, an `ENOENT` error has an `errno` of `-2` because the error
+code for `ENOENT` is `2`.
+In case of a string, it is the same as error.code
@shigeki

shigeki Jan 26, 2017

Contributor

I think it is better to fix like this. How is it?

--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -455,9 +455,11 @@ a sequence of capital letters, and may be referenced in `man 2 intro`.

 #### error.errno

-Returns a number corresponding to the **negated** error code, which may be
-referenced in `man 2 intro`. For example, an `ENOENT` error has an `errno` of
-`-2` because the error code for `ENOENT` is `2`.
+Returns a number or a string. The number corresponds to the
+**negated** error code, which may be referenced in `man 2 intro`. For
+example, an `ENOENT` error has an `errno` of `-2` because the error
+code for `ENOENT` is `2`.
+In case of a string, it is the same as error.code

This comment has been minimized.

@darai0512

darai0512 Jan 27, 2017

Contributor

I will modify it according to @shigeki advise.

@darai0512

darai0512 Jan 27, 2017

Contributor

I will modify it according to @shigeki advise.

doc/api/errors.md
+
+#### error.address
+
+Is a string describing the address that is not available in case of using some

This comment has been minimized.

@sam-github

sam-github Jan 25, 2017

Member

"When present, "....

Is it always an address that is not available? Can't it show up in errors for other reasons?

@sam-github

sam-github Jan 25, 2017

Member

"When present, "....

Is it always an address that is not available? Can't it show up in errors for other reasons?

This comment has been minimized.

@shigeki

shigeki Jan 26, 2017

Contributor

This appears only in the error that comes from net and dgram. I think that is why it was missed in the doc. I told him to add what modules it happens in. How about this?

When present (e.g. in net and dgram), it is a string describing the address that is not available. 
@shigeki

shigeki Jan 26, 2017

Contributor

This appears only in the error that comes from net and dgram. I think that is why it was missed in the doc. I told him to add what modules it happens in. How about this?

When present (e.g. in net and dgram), it is a string describing the address that is not available. 

This comment has been minimized.

@darai0512

darai0512 Jan 27, 2017

Contributor

OK, I will fix.

@darai0512

darai0512 Jan 27, 2017

Contributor

OK, I will fix.

This comment has been minimized.

@sam-github

sam-github Jan 27, 2017

Member

I like@shigeki's text, but I'm not sure what "not available means". It means that the address cannot be looked up?

@sam-github

sam-github Jan 27, 2017

Member

I like@shigeki's text, but I'm not sure what "not available means". It means that the address cannot be looked up?

This comment has been minimized.

@darai0512

darai0512 Jan 29, 2017

Contributor

@sam-github
Exactly, so I rewrite the description. Please review.

@darai0512

darai0512 Jan 29, 2017

Contributor

@sam-github
Exactly, so I rewrite the description. Please review.

doc/api/errors.md
+
+#### error.port
+
+Is a number of the connection's port that is refused in case of using some

This comment has been minimized.

@sam-github

sam-github Jan 25, 2017

Member

Doesn't it show for other reasons, such as connection reset?

@sam-github

sam-github Jan 25, 2017

Member

Doesn't it show for other reasons, such as connection reset?

This comment has been minimized.

@sam-github

sam-github Jan 25, 2017

Member

"When present, ..."

@sam-github

sam-github Jan 25, 2017

Member

"When present, ..."

This comment has been minimized.

@shigeki

shigeki Jan 26, 2017

Contributor

Doesn't it show for other reasons, such as connection reset?

Exactly. The same description of error.address as is not available seems to be better.

@shigeki

shigeki Jan 26, 2017

Contributor

Doesn't it show for other reasons, such as connection reset?

Exactly. The same description of error.address as is not available seems to be better.

doc/api/errors.md
#### error.syscall
-Returns a string describing the [syscall][] that failed.
+Is a string describing the [syscall][] that failed.

This comment has been minimized.

@sam-github

sam-github Jan 25, 2017

Member

"When present, ..."

@sam-github

sam-github Jan 25, 2017

Member

"When present, ..."

This comment has been minimized.

@darai0512

darai0512 Jan 29, 2017

Contributor

@sam-github
Excuse me, is there some cases without error.syscall property?

@darai0512

darai0512 Jan 29, 2017

Contributor

@sam-github
Excuse me, is there some cases without error.syscall property?

@jasnell

Almost there. It may also be worth documenting the error.name property.

doc/api/errors.md
@@ -250,7 +250,7 @@ not capture any frames.
#### error.message
-Returns the string description of error as set by calling `new Error(message)`.
+Is the string description of error as set by calling `new Error(message)`.

This comment has been minimized.

@jasnell

jasnell Jan 26, 2017

Member

I would prefer something like:

The `error.message` property is the...
@jasnell

jasnell Jan 26, 2017

Member

I would prefer something like:

The `error.message` property is the...

This comment has been minimized.

@darai0512

darai0512 Jan 27, 2017

Contributor

@jasnell Thanks for your review. I will fix.

@darai0512

darai0512 Jan 27, 2017

Contributor

@jasnell Thanks for your review. I will fix.

doc/api/errors.md
@@ -250,7 +250,7 @@ not capture any frames.
#### error.message
-Returns the string description of error as set by calling `new Error(message)`.
+Is the string description of error as set by calling `new Error(message)`.
The `message` passed to the constructor will also appear in the first line of
the stack trace of the `Error`, however changing this property after the
`Error` object is created *may not* change the first line of the stack trace.

This comment has been minimized.

@jasnell

jasnell Jan 26, 2017

Member

We should be clear here. I know this was already in the doc, but may not is not that clear. We should say whether it will or will not or indicate the conditions under which it may or may not.

@jasnell

jasnell Jan 26, 2017

Member

We should be clear here. I know this was already in the doc, but may not is not that clear. We should say whether it will or will not or indicate the conditions under which it may or may not.

This comment has been minimized.

@darai0512

darai0512 Jan 27, 2017

Contributor

I also got confused about its expression.
I know a simple example such as the following code.

Error.stackTraceLimit = 0;
var error = new Error('This will not change');
console.log(error.stack);
// Prints: Error: This will not change
error.message = 'not changed';
console.log(error.stack);
// Prints: Error: This will not change
Error.stackTraceLimit = 0;
var error = new Error('This will change');
error.message = 'changed';
console.log(error.stack);
// Prints: Error: changed

So, I will add the statement of (for example, when error.stack is set before this property is changed)

@darai0512

darai0512 Jan 27, 2017

Contributor

I also got confused about its expression.
I know a simple example such as the following code.

Error.stackTraceLimit = 0;
var error = new Error('This will not change');
console.log(error.stack);
// Prints: Error: This will not change
error.message = 'not changed';
console.log(error.stack);
// Prints: Error: This will not change
Error.stackTraceLimit = 0;
var error = new Error('This will change');
error.message = 'changed';
console.log(error.stack);
// Prints: Error: changed

So, I will add the statement of (for example, when error.stack is set before this property is changed)

@darai0512

This comment has been minimized.

Show comment
Hide comment
@darai0512

darai0512 Jan 29, 2017

Contributor

@jasnell

It may also be worth documenting the error.name property.

I think error.name belongs to ecma as Error.prototype.name originally.
https://www.ecma-international.org/ecma-262/7.0/#sec-error-objects

So, I think there is no necessity to explain it here. How about?

Contributor

darai0512 commented Jan 29, 2017

@jasnell

It may also be worth documenting the error.name property.

I think error.name belongs to ecma as Error.prototype.name originally.
https://www.ecma-international.org/ecma-262/7.0/#sec-error-objects

So, I think there is no necessity to explain it here. How about?

@sam-github

other than that the man page ref seems wrong on linux, LGTM

doc/api/errors.md
-Returns a string representing the error code, which is always `E` followed by
-a sequence of capital letters, and may be referenced in `man 2 intro`.
+The `error.code` property is a string representing the error code, which is always
+`E` followed by a sequence of capital letters, and may be referenced in `man 2 intro`.

This comment has been minimized.

@sam-github

sam-github Jan 31, 2017

Member

I don't see them refed on linux in the syscall intro, I do see them in man 3 errno.

@sam-github

sam-github Jan 31, 2017

Member

I don't see them refed on linux in the syscall intro, I do see them in man 3 errno.

This comment has been minimized.

@darai0512

darai0512 Feb 1, 2017

Contributor

@sam-github
Exactly. The command is already explained. So, I think there is no necessity to explain it here and in error.errno.
https://github.com/darai0512/node/blame/85341c7ae573c31c43ce05549e8f789138e047fd/doc/api/errors.md#L445-L446

@darai0512

darai0512 Feb 1, 2017

Contributor

@sam-github
Exactly. The command is already explained. So, I think there is no necessity to explain it here and in error.errno.
https://github.com/darai0512/node/blame/85341c7ae573c31c43ce05549e8f789138e047fd/doc/api/errors.md#L445-L446

@sam-github

This comment has been minimized.

Show comment
Hide comment
@sam-github

sam-github Jan 31, 2017

Member

This is close to ready, can you squash and rebase please?

Member

sam-github commented Jan 31, 2017

This is close to ready, can you squash and rebase please?

doc/api/errors.md
The `message` passed to the constructor will also appear in the first line of
the stack trace of the `Error`, however changing this property after the
-`Error` object is created *may not* change the first line of the stack trace.
+`Error` object is created *may not* change the first line of the stack trace
+(for example, when error.stack is set before this property is changed).

This comment has been minimized.

@mscdex

mscdex Feb 1, 2017

Contributor

'error.stack' here should have backticks around it.

@mscdex

mscdex Feb 1, 2017

Contributor

'error.stack' here should have backticks around it.

This comment has been minimized.

@darai0512

darai0512 Feb 1, 2017

Contributor

OK, I will fix: error.stack -> error.stack

@darai0512

darai0512 Feb 1, 2017

Contributor

OK, I will fix: error.stack -> error.stack

doc/api/errors.md
+The number corresponds to the **negated** error code, which may be referenced in
+`man 2 intro`. For example, an `ENOENT` error has an `errno` of `-2` because the
+error code for `ENOENT` is `2`.
+In case of a string, it is the same as error.code.

This comment has been minimized.

@mscdex

mscdex Feb 1, 2017

Contributor

'error.code' here should be surrounded by backticks.

@mscdex

mscdex Feb 1, 2017

Contributor

'error.code' here should be surrounded by backticks.

This comment has been minimized.

@darai0512

darai0512 Feb 1, 2017

Contributor

OK, I will fix: error.code -> error.code

@darai0512

darai0512 Feb 1, 2017

Contributor

OK, I will fix: error.code -> error.code

doc/api/errors.md
-referenced in `man 2 intro`. For example, an `ENOENT` error has an `errno` of
-`-2` because the error code for `ENOENT` is `2`.
+The `error.errno` property is a number or a string.
+The number corresponds to the **negated** error code, which may be referenced in

This comment has been minimized.

@mscdex

mscdex Feb 1, 2017

Contributor

Might want to double-check the applicability of this information to Windows systems ...

@mscdex

mscdex Feb 1, 2017

Contributor

Might want to double-check the applicability of this information to Windows systems ...

This comment has been minimized.

@darai0512

darai0512 Feb 1, 2017

Contributor

I fix about the command. I think it is already explained in L445-446, so there is no necessity to explain it again.

running man 2 intro or man 3 errno on most Unices; or [online][].

But exactly, it may not be referred to Windows systems.
I think 'online' is covered about it. How about?

@darai0512

darai0512 Feb 1, 2017

Contributor

I fix about the command. I think it is already explained in L445-446, so there is no necessity to explain it again.

running man 2 intro or man 3 errno on most Unices; or [online][].

But exactly, it may not be referred to Windows systems.
I think 'online' is covered about it. How about?

This comment has been minimized.

@mscdex

mscdex Feb 1, 2017

Contributor

I wasn't referring to the man reference, but instead the information about the error code being negated and such (e.g. the number may be positive on Windows from the start? is the number from the man pages still relevant for Windows -- does libuv normalize them on Windows?).

@mscdex

mscdex Feb 1, 2017

Contributor

I wasn't referring to the man reference, but instead the information about the error code being negated and such (e.g. the number may be positive on Windows from the start? is the number from the man pages still relevant for Windows -- does libuv normalize them on Windows?).

This comment has been minimized.

@darai0512

darai0512 Feb 2, 2017

Contributor

Sorry, I understood your point. The errno of this example may not be -2 on Windows. I will look over......

@darai0512

darai0512 Feb 2, 2017

Contributor

Sorry, I understood your point. The errno of this example may not be -2 on Windows. I will look over......

This comment has been minimized.

@shigeki

shigeki Feb 2, 2017

Contributor

@mscdex Good catch. Right, the Windows error is mapped to libuv error in https://github.com/nodejs/node/blob/master/deps/uv/src/win/error.c#L66 then allocated to an arbitrary negative number in uv-errno.h. I think that it is better not to describe this further here but just put reference to libuv.

diff --git a/doc/api/errors.md b/doc/api/errors.md
index 86d06fa..9a72cc9 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -458,9 +458,10 @@ The `error.code` property is a string representing the error code, which is alwa
 #### error.errno

 The `error.errno` property is a number or a string.
-The number corresponds to the **negated** error code. For example, an `ENOENT`
-error has an `errno` of `-2` because the error code for `ENOENT` is `2`.
-In case of a string, it is the same as `error.code`.
+The number corresponds to the **negated** error code which is defined
+in [`libuv Error handling`]. See uv-errno.h header file
+(`deps/uv/include/uv-errno.h` in the Node.js source tree) for
+details. In case of a string, it is the same as `error.code`.

 #### error.syscall

@@ -546,6 +547,7 @@ found [here][online].
 [`fs`]: fs.html
 [`http`]: http.html
 [`https`]: https.html
+[`libuv Error handling`]: http://docs.libuv.org/en/v1.x/errors.html
 [`net`]: net.html
 [`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception
 [domains]: domain.html
@shigeki

shigeki Feb 2, 2017

Contributor

@mscdex Good catch. Right, the Windows error is mapped to libuv error in https://github.com/nodejs/node/blob/master/deps/uv/src/win/error.c#L66 then allocated to an arbitrary negative number in uv-errno.h. I think that it is better not to describe this further here but just put reference to libuv.

diff --git a/doc/api/errors.md b/doc/api/errors.md
index 86d06fa..9a72cc9 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -458,9 +458,10 @@ The `error.code` property is a string representing the error code, which is alwa
 #### error.errno

 The `error.errno` property is a number or a string.
-The number corresponds to the **negated** error code. For example, an `ENOENT`
-error has an `errno` of `-2` because the error code for `ENOENT` is `2`.
-In case of a string, it is the same as `error.code`.
+The number corresponds to the **negated** error code which is defined
+in [`libuv Error handling`]. See uv-errno.h header file
+(`deps/uv/include/uv-errno.h` in the Node.js source tree) for
+details. In case of a string, it is the same as `error.code`.

 #### error.syscall

@@ -546,6 +547,7 @@ found [here][online].
 [`fs`]: fs.html
 [`http`]: http.html
 [`https`]: https.html
+[`libuv Error handling`]: http://docs.libuv.org/en/v1.x/errors.html
 [`net`]: net.html
 [`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception
 [domains]: domain.html

This comment has been minimized.

@darai0512

darai0512 Feb 3, 2017

Contributor

@mscdex PTAL

This comment has been minimized.

@mscdex

mscdex Feb 3, 2017

Contributor

@darai0512 It still shows the old text for this property?

@mscdex

mscdex Feb 3, 2017

Contributor

@darai0512 It still shows the old text for this property?

This comment has been minimized.

@darai0512

darai0512 Feb 3, 2017

Contributor

@mscdex Really? I corrected the text of error.errno along @shigeki 's proposal.

@darai0512

darai0512 Feb 3, 2017

Contributor

@mscdex Really? I corrected the text of error.errno along @shigeki 's proposal.

This comment has been minimized.

@shigeki

shigeki Feb 3, 2017

Contributor

@darai0512 My last proposal is

The `error.errno` property is a number or a string.
The number is a **negative** value which corresponds to the error code
defined in [`libuv Error handling`]. See uv-errno.h header file
(`deps/uv/include/uv-errno.h` in the Node.js source tree) for
details. In case of a string, it is the same as `error.code`.

The current your commit does not have it.

@shigeki

shigeki Feb 3, 2017

Contributor

@darai0512 My last proposal is

The `error.errno` property is a number or a string.
The number is a **negative** value which corresponds to the error code
defined in [`libuv Error handling`]. See uv-errno.h header file
(`deps/uv/include/uv-errno.h` in the Node.js source tree) for
details. In case of a string, it is the same as `error.code`.

The current your commit does not have it.

This comment has been minimized.

@darai0512

darai0512 Feb 4, 2017

Contributor

@mscdex @shigeki
Sorry, not 'the negated error code' but 'a negative value' because uv errno is used.
PTAL

@darai0512

darai0512 Feb 4, 2017

Contributor

@mscdex @shigeki
Sorry, not 'the negated error code' but 'a negative value' because uv errno is used.
PTAL

@darai0512

This comment has been minimized.

Show comment
Hide comment
@darai0512

darai0512 Feb 1, 2017

Contributor

@sam-github
I squash and rebase. Please check.

Contributor

darai0512 commented Feb 1, 2017

@sam-github
I squash and rebase. Please check.

@jasnell

jasnell approved these changes Feb 1, 2017

@sam-github sam-github requested a review from mscdex Feb 1, 2017

@sam-github

This comment has been minimized.

Show comment
Hide comment
@sam-github

sam-github Feb 1, 2017

Member

@mscdex had comments and needs to review

Member

sam-github commented Feb 1, 2017

@mscdex had comments and needs to review

@TimothyGu

While you are at it, please also add type annotations (like the ones in http)

doc/api/errors.md
@@ -250,10 +250,12 @@ not capture any frames.
#### error.message
-Returns the string description of error as set by calling `new Error(message)`.
+The `error.message` property is the string description of error as set by calling
+`new Error(message)`.
The `message` passed to the constructor will also appear in the first line of

This comment has been minimized.

@TimothyGu

TimothyGu Feb 2, 2017

Member

There should be either a paragraph break, or the lines should be wrapped together. It's not immediately clear what this is trying to do.

@TimothyGu

TimothyGu Feb 2, 2017

Member

There should be either a paragraph break, or the lines should be wrapped together. It's not immediately clear what this is trying to do.

This comment has been minimized.

@darai0512

darai0512 Feb 2, 2017

Contributor

Okay, I will change it to 1 line.

@darai0512

darai0512 Feb 2, 2017

Contributor

Okay, I will change it to 1 line.

doc/api/errors.md
The `message` passed to the constructor will also appear in the first line of
the stack trace of the `Error`, however changing this property after the
-`Error` object is created *may not* change the first line of the stack trace.
+`Error` object is created *may not* change the first line of the stack trace
+(for example, when `error.stack` is set before this property is changed).

This comment has been minimized.

@TimothyGu

TimothyGu Feb 2, 2017

Member

Can you elaborate on when error.stack is "set"?

@TimothyGu

TimothyGu Feb 2, 2017

Member

Can you elaborate on when error.stack is "set"?

This comment has been minimized.

@darai0512

darai0512 Feb 2, 2017

Contributor

I thought "called" was good at first. But it is good for not property but function.
"read" is good?

@darai0512

darai0512 Feb 2, 2017

Contributor

I thought "called" was good at first. But it is good for not property but function.
"read" is good?

doc/api/errors.md
-`-2` because the error code for `ENOENT` is `2`.
+The `error.errno` property is a number or a string.
+The number corresponds to the **negated** error code. For example, an `ENOENT`
+error has an `errno` of `-2` because the error code for `ENOENT` is `2`.

This comment has been minimized.

@TimothyGu

TimothyGu Feb 2, 2017

Member

Is ENOENT guaranteed to be 2 on all platforms by a specification? Or is it true de facto?

@TimothyGu

TimothyGu Feb 2, 2017

Member

Is ENOENT guaranteed to be 2 on all platforms by a specification? Or is it true de facto?

This comment has been minimized.

@darai0512

darai0512 Feb 2, 2017

Contributor

No, it may vary either on unix or on win32. @mscdex also refers to it. I will check it...

@darai0512

darai0512 Feb 2, 2017

Contributor

No, it may vary either on unix or on win32. @mscdex also refers to it. I will check it...

doc/api/errors.md
+#### error.port
+
+When present (e.g. in `net` or `dgram`), the `error.port` property is a number of
+the connection's port that is not available.

This comment has been minimized.

@TimothyGu

TimothyGu Feb 2, 2017

Member

"port that is not available" sounds too specific to me. Is port binding the only case in Node.js when err.port is present? Either way, I'd prefer "a relevant port number", which is intentionally vague but more future-proof.

Also, "... property is a number representing ..." sounds slightly better.

@TimothyGu

TimothyGu Feb 2, 2017

Member

"port that is not available" sounds too specific to me. Is port binding the only case in Node.js when err.port is present? Either way, I'd prefer "a relevant port number", which is intentionally vague but more future-proof.

Also, "... property is a number representing ..." sounds slightly better.

This comment has been minimized.

@darai0512

darai0512 Feb 2, 2017

Contributor

Thanks for your review. I will fix the following text.

=> the error.port property is a number representing the connection's port that is not available.

@darai0512

darai0512 Feb 2, 2017

Contributor

Thanks for your review. I will fix the following text.

=> the error.port property is a number representing the connection's port that is not available.

@darai0512

This comment has been minimized.

Show comment
Hide comment
@darai0512

darai0512 Feb 3, 2017

Contributor

@TimothyGu PTAL

Contributor

darai0512 commented Feb 3, 2017

@TimothyGu PTAL

doc/api/errors.md
-Returns the string description of error as set by calling `new Error(message)`.
+* {String}
+
+The `error.message` property is the string description of error as set by calling `new Error(message)`.

This comment has been minimized.

@mscdex

mscdex Feb 3, 2017

Contributor

s/of error/of the error/ or add backticks around 'error'

@mscdex

mscdex Feb 3, 2017

Contributor

s/of error/of the error/ or add backticks around 'error'

@darai0512

This comment has been minimized.

Show comment
Hide comment
@darai0512

darai0512 Feb 3, 2017

Contributor

PTAL

Contributor

darai0512 commented Feb 3, 2017

PTAL

@darai0512

This comment has been minimized.

Show comment
Hide comment
@darai0512

darai0512 Feb 7, 2017

Contributor

Sorry, I made a mistake about @shigeki 's proposal. So, I fixed it.
PTAL

Contributor

darai0512 commented Feb 7, 2017

Sorry, I made a mistake about @shigeki 's proposal. So, I fixed it.
PTAL

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.
@jasnell

jasnell approved these changes Feb 8, 2017

jasnell added a commit that referenced this pull request Feb 8, 2017

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.

PR-URL: #10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
@jasnell

This comment has been minimized.

Show comment
Hide comment
@jasnell

jasnell Feb 8, 2017

Member

Landed in fcedd71

Member

jasnell commented Feb 8, 2017

Landed in fcedd71

@jasnell jasnell closed this Feb 8, 2017

italoacasas added a commit to italoacasas/node that referenced this pull request Feb 9, 2017

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.

PR-URL: nodejs#10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

italoacasas added a commit to italoacasas/node that referenced this pull request Feb 14, 2017

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.

PR-URL: nodejs#10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

KryDos added a commit to KryDos/node that referenced this pull request Feb 25, 2017

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.

PR-URL: nodejs#10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

jasnell added a commit that referenced this pull request Mar 7, 2017

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.

PR-URL: #10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

jasnell added a commit that referenced this pull request Mar 7, 2017

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.

PR-URL: #10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

MylesBorins added a commit that referenced this pull request Mar 9, 2017

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.

PR-URL: #10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

@MylesBorins MylesBorins referenced this pull request Mar 9, 2017

Merged

v6.10.1 proposal #11759

MylesBorins added a commit that referenced this pull request Mar 9, 2017

doc: add and fix System Error properties
About path, address and port properties, these are not described though
being also represented as augmented Error objects with added properties.
And also, fix all property descriptions and add type annotations.

PR-URL: #10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

@MylesBorins MylesBorins referenced this pull request Mar 9, 2017

Merged

v4.8.1 proposal #11760

@darai0512 darai0512 deleted the darai0512:doc/errors branch Apr 5, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment