Add assertion error docs #19724

BridgeAR · 2018-04-01T08:33:06Z

This was never properly documented but it is used in the wild and it makes sense to actually explain how it works and what properties the errors contain. Those properties can be useful for the users.

Please note: I explicitly did not document the errorDiff option as I plan on removing it again in 10.x. It was introduced in v.9.9.x and I think we can still go ahead to remove it as it is unlikely that it is already used.

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

The AssertionError was always exposed but never properly documented. This explains how it is used and what options it accepts.

BridgeAR · 2018-04-01T08:33:41Z

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite/376/

vsemozhetbyt

With some nits)

vsemozhetbyt · 2018-04-01T08:42:39Z

doc/api/errors.md

-// AssertionError [ERR_ASSERTION]: 1 === 2
-```
+A subclass of `Error` that indicates the failure of an assertion. For further
+details check asserts [`Class: AssertionError`][].


~~asserts~~?

Add a comma after details and change check to see.

vsemozhetbyt · 2018-04-01T08:45:29Z

doc/api/errors.md

@@ -1680,6 +1675,7 @@ Creation of a [`zlib`][] object failed due to incorrect configuration.
 [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`require('crypto').setEngine()`]: crypto.html#crypto_crypto_setengine_engine_flags
 [`server.listen()`]: net.html#net_server_listen
+[`Class: AssertionError`]: assert.html#class_assertionerror


##assert_class_assertionerror?

Or, if the suggestions given below are valid, even #assert_class_assert_assertionerror.

vsemozhetbyt · 2018-04-01T08:49:54Z

doc/api/assert.md

+## Class: AssertionError
+
+A subclass of `Error` that indicates the failure of an assertion.
+All errors thrown by the assert module will be instance of the `AssertionError`


Not sure, but maybe instance -> instances?

assert module -> `assert` module (add backticks)

vsemozhetbyt · 2018-04-01T09:03:09Z

doc/api/assert.md

@@ -13,6 +13,71 @@ A `strict` and a `legacy` mode exist, while it is recommended to only use
 For more information about the used equality comparisons see
 [MDN's guide on equality comparisons and sameness][mdn-equality-guide].

+## Class: AssertionError


As this is not global, should not this be ## Class: assert.AssertionError?

Compare:
Class: net.Server and Class: net.Socket

vsemozhetbyt · 2018-04-01T09:04:56Z

doc/api/assert.md

+All errors thrown by the assert module will be instance of the `AssertionError`
+class.
+
+### new AssertionError(options)


The same.
Compare: new net.Server() and new net.Socket().

vsemozhetbyt · 2018-04-01T09:15:08Z

doc/api/assert.md

+  [`assert.strictEqual()`] is used.
+* `expected` {any} Set to the expected value in case e.g.,
+  [`assert.strictEqual()`] is used.
+* `generatedMessage` {boolean} Indicates if the message was auto generated


Not sure, but maybe auto generated -> auto-generated?

vsemozhetbyt · 2018-04-01T09:15:28Z

doc/api/assert.md

+* `generatedMessage` {boolean} Indicates if the message was auto generated
+  (`true`) or not.
+* `code` {string} This is always set to the string `ERR_ASSERTION` to indicate
+  that the error is actually a assertion error.


a assertion -> an assertion?

vsemozhetbyt · 2018-04-01T09:18:29Z

doc/api/assert.md

+```js
+const assert = require('assert');
+
+// Generate a AssertionError to compare the error message later:.


a AssertionError -> an AssertionError?

:. -> :?

vsemozhetbyt · 2018-04-01T09:28:30Z

doc/api/assert.md

+  assert.equal(err.expected, 2);
+  assert.equal(err.code, 'ERR_ASSERTION');
+  assert.equal(err.operator, '==');
+  assert.equal(err.generatedMessage, true);


Not sure if we should popularize legacy loose equality mode here.
Mabe this way?

const assert = require('assert'); // Generate an AssertionError to compare the error message later: const { message } = new assert.AssertionError({ actual: 1, expected: 2, operator: 'strictEqual' }); // Verify error output: try { assert.strictEqual(1, 2); } catch (err) { assert(err instanceof assert.AssertionError); assert.strictEqual(err.message, message); assert.strictEqual(err.name, 'AssertionError [ERR_ASSERTION]'); assert.strictEqual(err.actual, 1); assert.strictEqual(err.expected, 2); assert.strictEqual(err.code, 'ERR_ASSERTION'); assert.strictEqual(err.operator, 'strictEqual'); assert.strictEqual(err.generatedMessage, true); }

Or maybe with 1 and '1'?

Trott · 2018-04-01T16:46:24Z

doc/api/assert.md

+
+A subclass of `Error` that indicates the failure of an assertion.
+
+All instances contain the built-in Error properties (i.e., `message` and `name`)


Add backticks around Error.

Is i.e. the right abbreviation here? If so, then just get rid of i.e.. If not, change it to including or such as.

Trott · 2018-04-01T16:46:46Z

doc/api/assert.md

+A subclass of `Error` that indicates the failure of an assertion.
+
+All instances contain the built-in Error properties (i.e., `message` and `name`)
+plus the following:


plus the following: -> and:

Trott · 2018-04-01T16:49:39Z

Since there's substantial new text here: @nodejs/documentation

BridgeAR · 2018-04-01T17:33:54Z

Comments addressed.

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite/378/

vsemozhetbyt · 2018-04-01T18:10:40Z

doc/api/errors.md

@@ -365,7 +365,7 @@ detailed [here](#errors_system_errors).
 ## Class: AssertionError

 A subclass of `Error` that indicates the failure of an assertion. For further
-details check asserts [`Class: AssertionError`][].
+details, see [`Class: AssertionError`][].


AssertionError -> assert.AssertionError?

vsemozhetbyt · 2018-04-01T18:11:03Z

doc/api/errors.md

@@ -1675,7 +1675,7 @@ Creation of a [`zlib`][] object failed due to incorrect configuration.
 [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`require('crypto').setEngine()`]: crypto.html#crypto_crypto_setengine_engine_flags
 [`server.listen()`]: net.html#net_server_listen
-[`Class: AssertionError`]: assert.html#class_assertionerror
+[`Class: AssertionError`]: assert.html#assert_class_assert_assertionerror


AssertionError -> assert.AssertionError?

vsemozhetbyt · 2018-04-01T18:17:37Z

doc/api/assert.md

+* `generatedMessage` {boolean} Indicates if the message was auto-generated
+  (`true`) or not.
+* `code` {string} This is always set to the string `ERR_ASSERTION` to indicate
+  that the error is actually a assertion error.


Still a assertion -> an assertion?

Trott · 2018-04-01T23:02:16Z

doc/api/errors.md

-assert.strictEqual(1, 2);
-// AssertionError [ERR_ASSERTION]: 1 === 2
-```
+A subclass of `Error` that indicates the failure of an assertion. For further


Microscopic nit that can totally be ignored if you want: The word further can be omitted. For that matter, so can all of For further details,. It can just be See [`Class: AssertionError`][].

Trott · 2018-04-01T23:04:09Z

doc/api/errors.md

-// AssertionError [ERR_ASSERTION]: 1 === 2
-```
+A subclass of `Error` that indicates the failure of an assertion. For further
+details, see [`Class: AssertionError`][].


Should it now be Class: assert.AssertionError?

BridgeAR · 2018-04-02T11:02:26Z

New comments addressed.

New Lite-CI: https://ci.nodejs.org/job/node-test-pull-request-lite/390/

The AssertionError was always exposed but never properly documented. This explains how it is used and what options it accepts. PR-URL: nodejs#19724 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]>

PR-URL: nodejs#19724 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]>

BridgeAR · 2018-04-04T13:21:27Z

Landed in 5bdd6a7 and 3567ea0

The AssertionError was always exposed but never properly documented. This explains how it is used and what options it accepts. PR-URL: #19724 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]>

PR-URL: #19724 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]>

BridgeAR added 2 commits April 1, 2018 10:28

doc: properly document AssertionError

341ca32

The AssertionError was always exposed but never properly documented. This explains how it is used and what options it accepts.

doc: fix added value for assert module

7e23026

BridgeAR requested review from jasnell and Trott April 1, 2018 08:33

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 1, 2018

BridgeAR requested a review from vsemozhetbyt April 1, 2018 08:33

vsemozhetbyt added assert Issues and PRs related to the assert subsystem. errors Issues and PRs related to JavaScript errors originated in Node.js core. labels Apr 1, 2018

vsemozhetbyt approved these changes Apr 1, 2018

View reviewed changes

Trott reviewed Apr 1, 2018

View reviewed changes

fixup: address comments

5ae83c4

vsemozhetbyt reviewed Apr 1, 2018

View reviewed changes

Trott reviewed Apr 1, 2018

View reviewed changes

lpinca approved these changes Apr 2, 2018

View reviewed changes

fixup: address more comments

24b5e92

jasnell approved these changes Apr 2, 2018

View reviewed changes

BridgeAR added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 2, 2018

BridgeAR mentioned this pull request Apr 2, 2018

assert: add rawMessage to error messages #19723

Closed

4 tasks

BridgeAR closed this Apr 4, 2018

targos removed the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 4, 2018

targos pushed a commit that referenced this pull request Apr 6, 2018

doc: fix added value for assert module

9bddf92

PR-URL: #19724 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]>

BridgeAR deleted the add-assertion-error-docs branch April 1, 2019 23:40

BridgeAR restored the add-assertion-error-docs branch April 1, 2019 23:40

BridgeAR deleted the add-assertion-error-docs branch January 20, 2020 11:30


		A subclass of `Error` that indicates the failure of an assertion.

		All instances contain the built-in Error properties (i.e., `message` and `name`)

Uh oh!

Add assertion error docs #19724

Add assertion error docs #19724

Uh oh!

Conversation

BridgeAR commented Apr 1, 2018

Checklist

Uh oh!

BridgeAR commented Apr 1, 2018

Uh oh!

vsemozhetbyt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vsemozhetbyt Apr 1, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vsemozhetbyt Apr 1, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vsemozhetbyt Apr 1, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Trott commented Apr 1, 2018

Uh oh!

BridgeAR commented Apr 1, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BridgeAR commented Apr 2, 2018

Uh oh!

BridgeAR commented Apr 4, 2018

Uh oh!

Uh oh!

vsemozhetbyt Apr 1, 2018 •

edited

Loading

vsemozhetbyt Apr 1, 2018 •

edited

Loading

vsemozhetbyt Apr 1, 2018 •

edited

Loading