docs

ModuleIsomorphic

Code documentation generator for Simpl.js

Documentation

docsgeneratecodestringBlock...generateDomcodestringjsonparseFilepathstringcallbackBlock...stringifycodestringbreakLimit1numberstringstringifySpecspecValueTypebreakLimit1numberdepth0numbertypefalsebooleanstring

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 the parser module'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.

generateDom returns a DOM data structure suitable for the html.dom method, with elements tagged using docjs-prefixed class names.

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.

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.

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