doc-parser

DocBlock & Annotations Parser

This library is a javascript LALR(1) parser that parses docblocks and extracts annotations under an structured syntax tree.

Install

npm install doc-parser --save

And simple usage :

var DocParser = require('doc-parser');
var reader = new DocParser();
var data = reader.parse('/** @hello world */');

Supported syntaxes

/**
 * Some description
 * @return boolean
 * @return map<string, SomeClass>
 * @author Ioan CHIRIAC <[e-mail]>
 * @throws Exception
 * @deprecated
 * @table('tableName', true)
 * @table(
 *   name='tableName',
 *   primary=true
 * )
 * @annotation1 @annotation2
 * @Target(["METHOD", "PROPERTY"])
 * @Attributes([
 *   @Attribute("stringProperty", type = "string"),
 *   @Attribute("annotProperty",  type = "SomeAnnotationClass"),
 * ])
 * @json({
 *   "key": "value",
 *   "object": { "inner": true },
 *   "list": [1, 2, 3]
 * })
 * <node>
 * Some inner multi line content
 * </node>
 */

AST structure

{
  kind: 'doc',
  summary: 'Some description retrieved from the first line of the coment',
  body: [
    {
      kind: 'return',
      type: 'void',
      description: 'Some extra informations'
    }
  ]
}

Declaring custom doc blocks

By default, doc-parser supports @return,@param,@throws and @deprecated doc blocks.

You can extend the support to any doc block :

// lets handle @global (type) (var) (description)
var DocParser = require('doc-parser');
var reader = new DocParser({
  'global': [
    {
      property: 'type',
      parser: 'type',
      optional: true
    },
    {
      property: 'what',
      parser: 'variable',
      optional: true
    },
    {
      property: 'description',
      parser: 'text',
      optional: true,
      default: ''
    }
  ]
});
var data = reader.parse('/** @global string some description */');

This will result in a new kind of doc block with the specified properties. Here a list of supported parsers :

• type : a simple type, class name, or array of types
• variable : a variable name
• text : a line of text (will eat every token until the current line ends)
• version: a semantic version
• array : an array of items
• object : a json object definition
• boolean : a boolean
• number : a number (integer or float)
• string : a simple or double quoted text

Misc

This library is released under BSD-3 license clause.

Changelog

Version 0.4.6 (2017-1-27)

Patches

• fix gitignore: eac9a61

...full changes