https://github.com/glayzzle/doc-parser
:books: Documentation parser, doc blocks and annotations (fully compliant with phpDoc and doctrine annotations)
https://github.com/glayzzle/doc-parser
annotation-tool annotations docblock documentation documentation-tool parse parser
Last synced: 6 months ago
JSON representation
:books: Documentation parser, doc blocks and annotations (fully compliant with phpDoc and doctrine annotations)
- Host: GitHub
- URL: https://github.com/glayzzle/doc-parser
- Owner: glayzzle
- License: bsd-3-clause
- Created: 2017-01-05T09:35:16.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-07-26T04:18:39.000Z (almost 4 years ago)
- Last Synced: 2024-08-08T15:47:25.004Z (9 months ago)
- Topics: annotation-tool, annotations, docblock, documentation, documentation-tool, parse, parser
- Language: JavaScript
- Homepage:
- Size: 89.8 KB
- Stars: 12
- Watchers: 3
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# DocBlock & Annotations Parser
[](https://www.npmjs.com/package/doc-parser)
[](https://travis-ci.org/glayzzle/doc-parser)
[](https://coveralls.io/github/glayzzle/doc-parser?branch=master)
[](https://github.com/sindresorhus/xo)
[](https://gitter.im/glayzzle/Lobby)
This library is a javascript LALR(1) parser that parses docblocks and extracts
annotations under an structured syntax tree.
# Install
```sh
npm install doc-parser --save
```
And simple usage :
```js
var DocParser = require('doc-parser');
var reader = new DocParser();
var data = reader.parse('/** @hello world */');
```
# Supported syntaxes
```php
/**
* 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
```js
{
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 :
```js
// 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.