error docs for SystemErrors seems to partially predate the existence of the class

[sam-github]

I believe that when the SystemError class was introduced, the docs were not completely reworked to refer to it.

• https://nodejs.org/api/errors.html#errors_class_assertionerror Check the line above this link:

System-level errors are generated as augmented Error instances

Class inheritance is not usually called "augmentation", I think this line predates SystemError

• https://nodejs.org/api/errors.html#errors_system_errors

The nesting is weird, SystemError, https://nodejs.org/api/errors.html#errors_class_systemerror, should be at the same level as the other error classes above, but instead its nested inside this section, and the section says:

In Node.js, system errors are Error objects with extra properties.

This is strange, all the other error classes are documented with

Class: RangeError, A subclass of Error ...

Not "RangeError, an Error object with extra properties"!

I think the special section https://nodejs.org/api/errors.html#errors_system_errors needs to be removed, any useful information in it moved into the SystemError class docs, https://nodejs.org/api/errors.html#errors_class_systemerror, and the SystemError class docs should be outdented to the same level as all the other classes, and the doc text be brought into line with the other docs.

A number or sections, such as https://nodejs.org/api/errors.html#errors_errors, discuss "System errors", but its not clear whether all "System errors" are of class SystemError.

https://nodejs.org/api/errors.html#errors_common_system_errors and elsewhere imply that SystemError is usually a result of a failed syscall, but this isn't true, at least not anymore, there is a long list of error.code values for class SystemError that do not originate from a syscall: https://nodejs.org/api/errors.html#errors_node_js_error_codes

As I understand it, the situation is that there are a few classes of errors:

• Javascript, defined by V8/the JS standard
• System, defined by Node.js, with a class of SystemError.

SystemError has a .code (and other properties), and can be further broken down into two categories:

1. Those originating from a syscall, where the .code is going to mirror the macro name from man errno.
2. Those originating from node.js internally, where the .code we made up (and document in this page).

In short, I think the situation is as I summarize above, but the actual docs still have traces in their structure of the earlier state, and should be edited for clarity and structure.

I don't have the time ATM to do this, but this would make a good first contribution for someone wanting to get involved in improving our docs.

[JungMinu]

Going to open a PR for this