doc: improve example for Error.captureStackTrace()

[brodo]

Change the MyError example so that instances of MyError are instanceof Error and also native errors when checked with util.types.isNativeError().

[BridgeAR]

I see why you suggest this. I am not certain if the example becomes more difficult to read though, especially as it has new implications as outlined in my comment.

[brodo]

Should we maybe add a suggestion to use class MyError extends Error {}? Instances of this class will be instanceof Error and native errors. They will also not show the MyError constructor in the stack trace.

[brodo]

I see why you suggest this. I am not certain if the example becomes more difficult to read though, especially as it has new implications as outlined in my comment.

I understand the readability concern. Essentially it's a trade-off between having a 'copyable' example and a readable one. It would be interesting to find out if there are packages on npm that contain this error implementation...

[BridgeAR]

I am hesitant to change the documentation like that as we mix different APIs and errors should ideally not be created like that in the first place.

What about changing the example to show how to hide multiple call sites? E.g.,

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

That way we create a "real" error and only change it's stack trace accordingly.

[brodo]

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw new Error();
}

I like this example a lot. It illustrates the usage of the function much better. But shouldn't the last line be throw error;?

[brodo]

Is there anything else I need to do to so this can get merged?

[debadree25]

Could you rebase and update the first commit message, it seems the description exceeds the size limit of 72

[debadree25]

The example looks good, would also wait for @BridgeAR 's review to see if the changes address all his concerns.

[brodo]

Could you rebase and update the first commit message, it seems the description exceeds the size limit of 72

I've squashed all the commits and added line breaks.

[nodejs-github-bot]

Landed in 38e6ac7