From 59a1d00906e1b47f5cde38d6f7469e7c44105168 Mon Sep 17 00:00:00 2001
From: Daiki Arai <darai0512@yahoo.co.jp>
Date: Wed, 25 Jan 2017 00:49:53 +0900
Subject: [PATCH] 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: https://github.com/nodejs/node/pull/10986
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
---
 doc/api/errors.md | 62 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 52 insertions(+), 10 deletions(-)

diff --git a/doc/api/errors.md b/doc/api/errors.md
index 70588125a0..640935da35 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -195,6 +195,8 @@ will either be instances of, or inherit from, the `Error` class.
 
 ### new Error(message)
 
+* `message` {String}
+
 Creates a new `Error` object and sets the `error.message` property to the
 provided text message. If an object is passed as `message`, the text message
 is generated by calling `message.toString()`. The `error.stack` property will
@@ -205,6 +207,9 @@ given by the property `Error.stackTraceLimit`, whichever is smaller.
 
 ### Error.captureStackTrace(targetObject[, constructorOpt])
 
+* `targetObject` {Object}
+* `constructorOpt` {Function}
+
 Creates a `.stack` property on `targetObject`, which when accessed returns
 a string representing the location in the code at which
 `Error.captureStackTrace()` was called.
@@ -238,6 +243,8 @@ new MyError().stack
 
 ### Error.stackTraceLimit
 
+* {Number}
+
 The `Error.stackTraceLimit` property specifies the number of stack frames
 collected by a stack trace (whether generated by `new Error().stack` or
 `Error.captureStackTrace(obj)`).
@@ -250,10 +257,13 @@ not capture any frames.
 
 #### error.message
 
-Returns the string description of error as set by calling `new Error(message)`.
+* {String}
+
+The `error.message` property is the string description of the 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.
+`Error` object is created *may not* change the first line of the stack trace
+(for example, when `error.stack` is read before this property is changed).
 
 ```js
 const err = new Error('The message');
@@ -263,8 +273,10 @@ console.log(err.message);
 
 #### error.stack
 
-Returns a string describing the point in the code at which the `Error` was
-instantiated.
+* {String}
+
+The `error.stack` property is a string describing the point in the code at which
+the `Error` was instantiated.
 
 For example:
 
@@ -450,18 +462,47 @@ added properties.
 
 #### error.code
 
-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`.
+* {String}
+
+The `error.code` property is a string representing the error code, which is always
+`E` followed by a sequence of capital letters.
 
 #### 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`.
+* {String | Number}
+
+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`.
 
 #### error.syscall
 
-Returns a string describing the [syscall][] that failed.
+* {String}
+
+The `error.syscall` property is a string describing the [syscall][] that failed.
+
+#### error.path
+
+* {String}
+
+When present (e.g. in `fs` or `child_process`), the `error.path` property is a string
+containing a relevant invalid pathname.
+
+#### error.address
+
+* {String}
+
+When present (e.g. in `net` or `dgram`), the `error.address` property is a string
+describing the address to which the connection failed.
+
+#### error.port
+
+* {Number}
+
+When present (e.g. in `net` or `dgram`), the `error.port` property is a number representing
+the connection's port that is not available.
 
 ### Common System Errors
 
@@ -528,6 +569,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