Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
sam-github opened this issue Mar 22, 2019 · 1 comment
Assignees
Labels
doc Issues and PRs related to the documentations. good first issue Issues that are suitable for first-time contributors.

Comments

@sam-github
Copy link
Contributor

sam-github commented Mar 22, 2019

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

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:

  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.

@sam-github sam-github added doc Issues and PRs related to the documentations. good first issue Issues that are suitable for first-time contributors. labels Mar 22, 2019
@JungMinu
Copy link
Member

JungMinu commented Mar 24, 2019

Going to open a PR for this

@JungMinu JungMinu self-assigned this Mar 24, 2019
BethGriggs pushed a commit that referenced this issue Apr 4, 2019
Remove old errors_system_errors, any useful information
in it moved into the SystemError class docs.

Fixes: #26861
PR-URL: #27037
Reviewed-By: Sam Roberts <[email protected]>
BethGriggs pushed a commit that referenced this issue Apr 9, 2019
Remove old errors_system_errors, any useful information
in it moved into the SystemError class docs.

Fixes: #26861
PR-URL: #27037
Reviewed-By: Sam Roberts <[email protected]>
Signed-off-by: Beth Griggs <[email protected]>
BethGriggs pushed a commit that referenced this issue Apr 10, 2019
Remove old errors_system_errors, any useful information
in it moved into the SystemError class docs.

Fixes: #26861
PR-URL: #27037
Reviewed-By: Sam Roberts <[email protected]>
Signed-off-by: Beth Griggs <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. good first issue Issues that are suitable for first-time contributors.
Projects
None yet
Development

No branches or pull requests

2 participants