Skip to content

Commit

Permalink
doc: simplify "is recommended" language in assert documentation
Browse files Browse the repository at this point in the history
Replace "X is not recommended" with  "Avoid X".
Replace "It is recommended not to use X" with "Avoid X".

PR-URL: #30558
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
  • Loading branch information
Trott authored and BethGriggs committed Feb 6, 2020
1 parent 50b7f84 commit b7bd84f
Showing 1 changed file with 7 additions and 6 deletions.
13 changes: 7 additions & 6 deletions doc/api/assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -1234,10 +1234,11 @@ assert.throws(
(err) => {
assert(err instanceof Error);
assert(/value/.test(err));
// Returning anything from validation functions besides `true` is not
// recommended. Doing so results in the caught error being thrown again.
// That is usually not the desired outcome. Throw an error about the
// specific validation that failed instead (as done in this example).
// Avoid returning anything from validation functions besides `true`.
// Otherwise, it's not clear what part of the validation failed. Instead,
// throw an error about the specific validation that failed (as done in this
// example) and add as much helpful debugging information to that error as
// possible.
return true;
},
'unexpected error'
Expand Down Expand Up @@ -1288,8 +1289,8 @@ assert.throws(throwingFirst, /Second$/);
// at throwingFirst (repl:2:9)
```

Due to the confusing notation, it is recommended not to use a string as the
second argument. This might lead to difficult-to-spot errors.
Due to the confusing error-prone notation, avoid a string as the second
argument.

[`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
[`ERR_INVALID_RETURN_VALUE`]: errors.html#errors_err_invalid_return_value
Expand Down

0 comments on commit b7bd84f

Please sign in to comment.