Code example in the docs of Error.captureStackTrace needs better wording

[jaymuthus]

Ref: https://nodejs.org/dist/latest-v7.x/docs/api/errors.html#errors_error_capturestacktrace_targetobject_constructoropt

function MyError() {
  Error.captureStackTrace(this, MyError);
}

// Without passing MyError to captureStackTrace, the MyError
// frame would show up in the .stack property. By passing
// the constructor, we omit that frame and all frames above it.
new MyError().stack;

Result:

Error
    at Object.<anonymous> (/Users/mjayaraman/SVNFiles/node/course/error.js:8:11)
    at Module._compile (module.js:541:32)
    at Object.Module._extensions..js (module.js:550:10)
    at Module.load (module.js:458:32)
    at tryModuleLoad (module.js:417:12)
    at Function.Module._load (module.js:409:3)
    at Function.Module.runMain (module.js:575:10)
    at startup (node.js:160:18)
    at node.js:456:3

function MyError() {
  Error.captureStackTrace(this);
}

// Without passing MyError to captureStackTrace, the MyError
// frame would show up in the .stack property. By passing
// the constructor, we omit that frame and all frames above it.
new MyError().stack;

Error
    at new MyError (/Users/mjayaraman/SVNFiles/node/course/error.js:2:9)
    at Object.<anonymous> (/Users/mjayaraman/SVNFiles/node/course/error.js:8:11)
    at Module._compile (module.js:541:32)
    at Object.Module._extensions..js (module.js:550:10)
    at Module.load (module.js:458:32)
    at tryModuleLoad (module.js:417:12)
    at Function.Module._load (module.js:409:3)
    at Function.Module.runMain (module.js:575:10)
    at startup (node.js:160:18)
    at node.js:456:3

Meaning, it just omits that frame, if we pass the constructor and not the above frames.

// the constructor, we omit that frame and all frames above it. 

To be changed to

// the constructor, we omit that frame.

or

// the constructor, we omit that frame, and retain all frames above it.

• Version:
• Platform:
• Subsystem:

[gibfahn]

https://github.com/nodejs/node/blob/master/doc/api/errors.md#errorcapturestacktracetargetobject-constructoropt

Added in #789, based on that maybe cc/ @Fishrock123 @jasnell @trevnorris ?

[refack]

Meaning, it just omits that frame, if we pass the constructor and not the above frames.

Above, not below 😉.
But I agree it could be better worded.

[refack]

Meaning, it just omits that frame, if we pass the constructor and not the above frames.

It actual meaning is that it omits the frames that are deeper than the call point.

function foo() {
  bar()
}

function bar() {
  baz()
}

function baz() {
  function MyError() {
    Error.captureStackTrace(this, bar)
  }
  var e = new MyError()
  console.log(e.stack)
}

foo()

> foo()
Error
    at foo (repl:3:1)
    at repl:2:1
    at REPLServer.defaultEval (repl.js:339:29)
    at bound (domain.js:280:14)
    at REPLServer.onLine (repl.js:536:10)
    at emitOne (events.js:101:20)
    at REPLServer.emit (events.js:191:7)
    at REPLServer.Interface._onLine (readline.js:241:10)
    at REPLServer.Interface._line (readline.js:590:8)
    at REPLServer.Interface._ttyWrite (readline.js:869:14)
undefined

[joyeecheung]

Edited the title to be clearer about what this issue is about.

[arturgvieira-zz]

Hi, I made the change, please let me know if its good to go. Thanks