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.3.0 (2017-1-9)

Major Changes

• rewrite parser structure (xo++): edda0c4
• start to define generic parsers for grammar: ffbe9c3
• rename package: 6b01724
• implement type, text & tests: 7ff0b34

Minor Changes

• fix xo on tests: ddde5f8
• extract summary: 1134c84
• add a backup function & implement float numbers: 0802ad5
• add new symbols: 6216fe0
• implement the variable reader: cf2eb94
• implement semver parser & deprecated block + test: afedeff
• implement object parsing: 9861453

Patches

• beautify: caa80e6
• improve tests: 2c8e479
• fix lexer & cover with tests: 0356720
• fix tests: 1064114
• update badges: 060206d
• update badges: 2d2422e
• update coveralls token: 6cd7ba1
• up nodejs version: 6677f79
• fix the backup state reverse: ca58ab2
• improve the documentation: a676169
• fix point symbol / tests: 897be4d
• rewrite next token eating: 547b20f
• improve tests & fix array parsing: ecbe333
• fix type parser & improve coverage: f17d295

...full changes