[Pkg-javascript-commits] [node-stack-utils] 13/67: documentation

[Bastien Roucariès]

This is an automated email from the git hooks/post-receive script.

rouca pushed a commit to branch master
in repository node-stack-utils.

commit aa72622d05bb461d56319777edf1d49c4f19da9d
Author: James Talmage <james at talmage.io>
Date:   Mon Jan 4 23:25:19 2016 -0500

    documentation
---
 readme.md | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 89 insertions(+), 7 deletions(-)

diff --git a/readme.md b/readme.md
index 62081fa..40156f0 100644
--- a/readme.md
+++ b/readme.md
@@ -27,22 +27,104 @@ console.log(stack.clean(new Error().stack));
 
 ## API
 
-### stackUtils(input, [options])
 
-#### input
+### new StackUtils([options])
+
+Creates a new `stackUtils` instance.
+
+#### options
+
+##### internals
+
+Type: `array` of `RegularExpression`s  
+
+A set of regular expressions that match internal stack stack trace lines which should be culled from the stack trace.
+`StackUtils.nodeInternals()` returns a relatively set of sensible defaults for use on the node platform.
+
+##### cwd
 
 Type: `string`
 
-Lorem ipsum.
+The path to the current working directory. File names in the stack trace will be shown relative to this directory.
+
+
+### StackUtils.nodeInternals()
+
+Returns an array of regular expressions that be used to cull lines from the stack trace that reference common Node.js internal files.
+
+
+### stackUtils.clean(stack)
+
+Cleans up a stack trace by deleting any lines that match the `internals` passed to the constructor, and shortening file names relative to `cwd`.
+
+Returns a `string` with the cleaned up stack (always terminated with a `\n` newline character).
+
+#### stack
+
+*Required*  
+Type: `string` or an `array` of `string`s
+
+
+### stackUtils.capture([options])
+
+Captures the current stack trace, returning an array of `CallSite`s. There are good overviews of the available CallSite methods [here](https://github.com/v8/v8/wiki/Stack%20Trace%20API#customizing-stack-traces), and [here](https://github.com/sindresorhus/callsites#api).
 
 #### options
 
-##### foo
+##### limit
+
+Type: `number`
+Default: `Infinity`
+
+Limits the number of lines returned by dropping all lines in excess of the limit. This removes lines from the stack trace.
+
+##### startStackFunction
+
+Type: `function`
+
+The function where the stack trace should start. The first line of the stack trace will be the function that called `startStackFunction`. This removes lines from the end of the stack trace.
+
+
+### stackUtils.captureString([options])
+
+Captures the current stack trace, cleans it using `stackUtils.clean(stack)`, and returns a string with the cleaned stack trace.
+ 
+#### options
+
+`captureString` has the same available options as `capture`
+
+
+### stackUtils.at([startStackFunction])
+
+Captures the first line of the stack trace (or the first line after `startStackFunction` if supplied), and returns a `CallSite` like object that is serialization friendly (properties are actual values instead of getter functions). 
+
+The available properties are:
+
+ - `line`: `number` 
+ - `column`: `number`
+ - `file`: `string`
+ - `constructor`: `boolean`
+ - `evalOrigin`: `string`
+ - `native`: `boolean`
+ - `typename`: `string`
+ - `function`: `string`
+ - `method`: `string`
+
+### stackUtils.parseLine(line)
 
-Type: `boolean`  
-Default: `false`
+Parses a `string` (which should be a single line from a stack trace), and generates an object with the following properties:
 
-Lorem ipsum.
+ - `line`: `number` 
+ - `column`: `number`
+ - `file`: `string`
+ - `constructor`: `boolean`
+ - `evalOrigin`: `string`
+ - `evalLine`: `number`
+ - `evalColumn`: `number`
+ - `evalFile`: `string`
+ - `native`: `boolean`
+ - `function`: `string`
+ - `method`: `string`
 
 
 ## License

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-stack-utils.git