error docs for SystemErrors seems to partially predate the existence of the class #26861
Description
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
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:
- Those originating from a syscall, where the
.codeis going to mirror the macro name fromman errno. - Those originating from node.js internally, where the
.codewe 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.