npm version Build Status Coverage Status XO code style Gitter
This library is a javascript LALR(1) parser that parses docblocks and extracts annotations under an structured syntax tree.
npm install doc-parser --save
And simple usage :
var DocParser = require('doc-parser'); var reader = new DocParser(); var data = reader.parse('/** @hello world */');
/** * Some description * @return boolean * @return map<string, SomeClass> * @author Ioan CHIRIAC <me@domain.com> * @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> */
{ kind: 'doc', summary: 'Some description retrieved from the first line of the coment', body: [ { kind: 'return', type: 'void', description: 'Some extra informations' } ] }
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
This library is released under BSD-3 license clause.