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 = ;var reader = ;var data = reader;
Supported syntaxes
/** * Some description * @return boolean * @return map * @author Ioan CHIRIAC * @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] * }) * * Some inner multi line content * */
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 = ;var reader = 'global': property: 'type' parser: 'type' optional: true property: 'what' parser: 'variable' optional: true property: 'description' parser: 'text' optional: true default: '' ;var data = reader;
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.