Comment Parser
Parse source file comments
Fast, streaming and configurable comment parser; currently supports 30+ languages.
Designed for polyglot programmers to:
- Combine comments from various files (HTML, CSS and Javascript for example)
- Parse comments from any language
- Strip comments from any file
- Separate comments into another file
- Implement custom tag systems (annotations)
- Operate on processing instructions (see the pi language)
- Document JSON files, read comments then strip in build process
See the i/o sample and the api docs.
Install
npm i mkparse --save
For the command line interface install mkdoc globally (npm i -g mkdoc
).
Usage
Parse a string or buffer:
var mkparse = stream = mkparse;stream;
Load and parse file contents:
var mkparse = stream = mkparse;stream;
Parse and write comment data to file as newline delimited JSON:
var mkparse = fs = stream = mkparse;stream;
Use a language pack:
var mkparse = stream = mkparse;stream;
Combine language pack rules:
var mkparse = stream = mkparse;stream;
For more detail see the api docs.
Example
Print comments in a file:
mkparse index.js
Print as json:
mkparse lib/*.js -j
Print the source content without comments:
mkparse index.js -s
Comments
A comment consists of a multi-line description and optional tag annotations:
/** * Method description * that can span multiple lines. * * @name method */ // Method description// that can span multiple lines.//// @name method
All the following comments resolve to the same description with the default settings:
/** Comment description */ /** * Comment description */ /************************* * Comment description * ************************/ // Comment description // //// Comment description//
Tags
Tags allow annotating a comment with meaningful information to consumers of the comment data.
The tag parser recognises tags beginning with an @
and is able to parse type
,
value
(default), name
, description
and an optional
flag.
Grammar for the default tag parser:
@id {type=value} [name] description
All fields but the tag id
are considered optional, to set the optional
flag
enclose name
in square brackets ([]
).
When given @property {String=mkdoc} [nickname] user
it expands to a tag object such as:
id: 'property' type: 'String' value: 'mkdoc' name: 'nickname' description: 'user' optional: true
See the tag api docs to change the tag parsing.
Block
By default continuous single-line comments are gathered into a single comment
object. The
rule is that if the next line does not match whitespace followed by the start of a
single-line comment then the block is terminated.
Note that inline comments also break the block:
// // Comment description// var foo; // Separate inline comment
Will result in two comments, whilst:
// Comment description// // More information.
Results in a single comment.
Help
Usage: mkparse [options] <files...>
Parse source file comments.
Options
-l, --lang=[LANG] Set language for all files
-s, --strip Print content only, remove comments
-c, --content Include non-comment content
-d, --dotted Parse dotted names
-j, --json Print comments as JSON
-i, --indent=[NUM] Number of spaces for JSON (default: 0)
-h, --help Display help and exit
--version Print the version and exit
mkparse@1.5.9
License
MIT
Created by mkdoc on April 18, 2016