kganser.com

doc.js

Doc.js is a simple inline documentation parser written in javascript for javascript. It uses jscc to parse a custom javascript spec syntax from comments in source code.

Installation

Use the doc-jsml wrapper script and stylesheet to render documentation in-browser from a script document requested via ajax. This script uses jsml to render json output from the doc.js library script as DOM.

<!-- in head tag -->
<link rel="stylesheet" href="//docjs.kganser.com/doc-jsml.css">

<div id="docs"></div>

<!-- before closing body tag -->
<script src="//jsml.kganser.com/jsml.js"></script>
<script src="//docjs.kganser.com/doc.js"></script>
<script src="//docjs.kganser.com/doc-jsml.js"></script>
<script>
  doc('/doc-jsml.js', document.getElementById('docs'));
</script>
generated from source by doc.js
docpathstringelementDOMElement

Populates element with documentation generated by doc.js and rendered with jsml using code retrieved with an ajax request to the specified path.

Library

generated from source by doc.js
docgeneratecodestringBlock...stringifycodestringbreakLimit1numberstringstringifySpecspecValueTypebreakLimit1numberdepth0numbertypefalsebooleanstringparseFilepathstringcallbackBlock...

Documentation is parsed from comments in code beginning with /**, which are split into blocks separated by one or more empty lines. The first block is parsed using the doc spec grammar below. If the parse succeeds, the result is returned in spec. Otherwise, spec is null, error is set to jscc's ParseError, and the block is parsed as text along with subsequent blocks.

        <spec> ::= <id> ':' <types>
 <named_value> ::= <id> '=' <literal> ':' <types>
                 | <spec>
                 | '...'
<named_values> ::= <named_value> ',' <named_values>
                 | <named_value>
       <value> ::= <named_value>
                 | <types>
      <values> ::= <value> ',' <values>
                 | <value>
        <type> ::= <id>
                 | 'function'
                 | 'function' '(' <values> ')'
                 | '{' <named_values> '}'
                 | '[' <values> ']'
       <types> ::= <type> '|' <types>
                 | 'function' '->' <types>
                 | 'function' '(' <values> ')' '->' <types>
                 | <type>
     <literal> ::= 'null' | 'undefined' | 'true' | 'false' | <string> | <number> | <code>

See source for regular expressions corresponding to <id>, <string>, <number>, and <code>, and for examples.

Text blocks following the spec block support code spans between backticks. If an entire block is surrounded in backticks, it is parsed as a preformatted block aligned with the right side of the opening backtick.

stringify returns a plain-text version of the doc structure returned by generate, and stringifySpec does the same for the spec structure within Block. breakLimit sets the depth at which nested object properties stop being separated by line breaks.

parseFile is a convenience method that makes an ajax request for the file at path, calls generate on the response text, and issues callback with the result.

BlockspecValuenullerrorParseErrorundefinedtextstringcodestring...prestring...
ValueValue...stringnamestringundefineddefaultstringundefinedtypeType
TypeType...stringfunctionargsValuereturnsTypeundefinedobjectValuearrayValue