tunic

A documentation-block parser. Generates a DocTree abstract syntax tree using a customizable regular-expression grammar. Defaults to parsing C-style comment blocks, so it supports C, C++, Java, JavaScript, PHP, and even CSS right out of the box.

Documentation blocks follow the conventions of other standard tools such as Javadoc, JSDoc, Google Closure, PHPDoc, etc. The primary difference is that nothing is inferred from the code. If you want it documented, you must document it. This is why you can use tunic to parse inline documentation out of almost any language that supports multi-line comments.

Tags are parsed greedily. If it looks like a tag, it's a tag. What you do with them is completely up to you. Render something human-readable, perhaps?

Install

$ npm install --save tunic

Usage

var tunic = require('tunic');
 
// parse javadoc-style comments
var jsDocAst = tunic.parse('/** ... */');
 
// parse Mustache and Handlebars comments
var hbDocAst = tunic.parse('{{!--- ... --}}', {
    blockIndent: /^[\t !]/gm,
    blockParse: /^[\t ]*\{\{!---(?!-)([\s\S]*?)\s*--\}\}/m,
    blockSplit: /(^[\t ]*\{\{!---(?!-)[\s\S]*?\s*--\}\})/m,
    namedTags: ['element', 'attribute']
});

Or with ES6:

import {parse} from 'tunic';
 
// parse perlpod-style comments
const perlDocAst = parse('=pod\n ... \n=cut', {
    blockParse: /^=pod\n([\s\S]*?)\n=cut$/m,
    blockSplit: /(^=pod\n[\s\S]*?\n=cut$)/m,
    tagSplit: false
});

API

tunic.parse(code[, grammar]) : DocTree

• code {String} - Block of code containing comments to parse.
• grammar {?Object} - Optional grammar definition.
  • blockIndent {RegExp} - Matches any valid leading indentation characters, such as whitespace or asterisks. Used for unwrapping comment blocks.
  • blockParse {RegExp} - Matches the content of a comment block, where the first capturing group is the content without the start and end comment characters. Used for normalization.
  • blockSplit {RegExp} - Splits code and docblocks into alternating chunks.
  • tagParse {RegExp} - Matches the various parts of a tag where parts are captured in the following order:
    • 1: tag
    • 2: type
    • 3: name
    • 4: description
  • tagSplit {RegExp} - Matches characters used to split description and tags from each other.
  • namedTags {Array.<String>} - Which tags should be considered "named" tags. Non-named tags will have their name prepended to the description and set to undefined.

Parses a given string and returns the resulting DocTree AST object. Defaults to parsing C-style comment blocks.

Languages

Several pre-defined grammars are available. To use, import the desired grammar and pass it to the parser.

var parse = require('tunic').parse;
var grammar = require('tunic/grammars/css');
 
var cssDocAst = parse('/** ... */', grammar); // -> ast object

Or with ES6:

import {parse} from 'tunic';
import * as grammar from 'tunic/grammars/css';
 
const cssDocAst = parse('/** ... */', grammar); // -> ast object

Test

$ npm test

Contribute

Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.

© 2016 Shannon Moeller me@shannonmoeller.com

Licensed under MIT