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.
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>
docpathstringelementDOMElement
Populates element
with documentation generated by doc.js and rendered with jsml using code retrieved with an ajax request to the specified path
.
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