Documentation for a single class.

Represents the documentation for an entire codebase.

Base class for all classes that represent a parsed comment of some sort.

Exception raised if there is a cyclic dependency.

Represents documentaion for an entire file. The constructor takes the source text for file, parses it, then provides a class wrapper around the parsed text.

Documentation for a single function or method. Takes a parsed comment and provides accessors for accessing the various fields.

Exception raised if a file references a dependency that doesn't exist.

Represents the top-level fileoverview documentation.

Represents a parameter, option, or parameter-like object, basically anything that has a name, a type, and a description, separated by spaces. This is also used for return types and exceptions, which use an empty string for the name.

For < Python2.5 compatibility.

Build a graph where nodes are filenames and edges are reverse dependencies (so an edge from jquery.js to jquery.dimensions.js indicates that jquery.js must be included before jquery.dimensions.js). The graph is represented as a dictionary from filename to (in-degree, edges) pair, for ease of topological sorting. Also returns a list of nodes of degree zero.

Build the simple tag skeleton for a title and body.

Sort the dependency graph, taking in a list of starting module names and a CodeBaseDoc (or equivalent dictionary). Returns an ordered list of transitive dependencies such that no module appears before its dependencies.

Return the first sentence of a string - everything up to the period, or the whole text if there is no period.

>>> first_sentence('')
''
>>> first_sentence('Incomplete')
''
>>> first_sentence('The first sentence.  This is ignored.')
'The first sentence.'

Flatten an iterator of iterators into a single, long iterator, exhausting each subiterator in turn.

>>> flatten([[1, 2], [3, 4]])
[1, 2, 3, 4]

Return a list of all documentation comments in the file text. Each comment is a pair, with the first element being the comment text and the second element being the line after it, which may be needed to guess function & arguments.

>>> get_doc_comments(read_file('examples/module.js'))[0][0][:40]
'/**\n * This is the module documentation.'
>>> get_doc_comments(read_file('examples/module.js'))[1][0][7:50]
'This is documentation for the first method.'
>>> get_doc_comments(read_file('examples/module.js'))[1][1]
'function the_first_function(arg1, arg2) '
>>> get_doc_comments(read_file('examples/module.js'))[2][0]
'/** This is the documentation for the second function. */'

Return a list of all JS files, given the root paths.

Return a list of all root paths where JS files can be found, given the command line options (in dict form) for this script.

Attempt to determine the function name from the first code line following the comment. The patterns recognized are described by regexps, which defaults to FUNCTION_REGEXPS. If a match is successful, returns the function name. Otherwise, returns None.

Attempt to guess parameters based on the presence of a parenthesized group of identifiers. If successful, returns a list of parameter names; otherwise, returns None.

Convert paragraphs delimited by blank lines into HTML text enclosed in <p> tags.

Return true if the filename ends in .js and is not a packed or minified file (no '.pack' or '.min' in the filename)

>>> is_js_file('jquery.min.js')
False
>>> is_js_file('foo.json')
False
>>> is_js_file('ui.combobox.js')
True

Generator for all JavaScript files in the directory, recursively

>>> 'examples/module.js' in list(list_js_files('examples'))
True

Main command-line invocation.

Generate the HTML index (a short description and a link to the full documentation) for a list of FunctionDocs or ClassDocs.

Split the raw comment text into a dictionary of tags. The main comment body is included as 'doc'.

>>> comment = get_doc_comments(read_file('examples/module.js'))[4][0]
>>> parse_comment(strip_stars(comment), '')['doc']
'This is the documentation for the fourth function.\n\n Since the function being documented is itself generated from another\n function, its name needs to be specified explicitly. using the @function tag'
>>> parse_comment(strip_stars(comment), '')['function']
'not_auto_discovered'

If there are multiple tags with the same name, they're included as a list:

>>> parse_comment(strip_stars(comment), '')['param']
['{String} arg1 The first argument.', '{Int} arg2 The second argument.']

Return a list of all parsed comments in a file. Mostly for testing & interactive use.

Turn a Python identifier into something fit for human consumption.

>>> printable('author')
'Author'
>>> printable('all_dependencies')
'All Dependencies'

Open a file, reads it into a string, closes the file, and returns the file text.

Run the no-arg function action if any of names appears in the option dict opts.

Save a string to a file. If the containing directory(ies) doesn't exist, this creates it.

Generator that walks the text and splits it into an array on split_by, being careful not to break inside a delimiter pair. delimiters should be an even-length string with each pair of matching delimiters listed together, open first.

>>> list(split_delimited('{}[]', ',', ''))
['']
>>> list(split_delimited('', ',', 'foo,bar'))
['foo', 'bar']
>>> list(split_delimited('[]', ',', 'foo,[bar, baz]'))
['foo', '[bar, baz]']
>>> list(split_delimited('{}', ' ', '{Type Name} name Desc'))
['{Type Name}', 'name', 'Desc']
>>> list(split_delimited('[]{}', ',', '[{foo,[bar, baz]}]'))
['[{foo,[bar, baz]}]']

Two adjacent delimiters result in a zero-length string between them:

>>> list(split_delimited('{}', ' ', '{Type Name}  Desc'))
['{Type Name}', '', 'Desc']

split_by may be a predicate function instead of a string, in which case it should return true on a character to split.

>>> list(split_delimited('', lambda c: c in '[]{}, ', '[{foo,[bar, baz]}]'))
['', '', 'foo', '', 'bar', '', 'baz', '', '', '']

Split the JSDoc tag text (everything following the @) at the first whitespace. Returns a tuple of (tagname, body).

Strip leading stars from a doc comment.

>>> strip_stars('/** This is a comment. */')
'This is a comment.'
>>> strip_stars('/**\n * This is a\n * multiline comment. */')
'This is a\n multiline comment.'
>>> strip_stars('/** \n\t * This is a\n\t * multiline comment. \n*/')
'This is a\n multiline comment.'

Perform a topological sort on the dependency graph dependencies, starting from list start_nodes.

If filename ends with .js, trims the extension off.

>>> trim_js_ext('foo.js')
'foo'
>>> trim_js_ext('something_else.html')
'something_else.html'

Print out a warning on STDERR.