s/mudules/modules/

@mscdex Thanks for your review.

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.

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

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

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

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...

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

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

'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
I understood. I will fix.

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;

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

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.

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?

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.

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

I will modify it according to @shigeki advise.

"When present, "....

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

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. 

OK, I will fix.

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
Exactly, so I rewrite the description. Please review.

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

"When present, ..."

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.

"When present, ..."

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

I would prefer something like:

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

@jasnell Thanks for your review. I will fix.

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.

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)

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

@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

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

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

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

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

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

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?

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?).

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

@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

@mscdex PTAL

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

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

@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.

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

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.

Okay, I will change it to 1 line.

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

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

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

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

"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.

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.

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