Parse source file comments

Usage no npm install needed!

<script type="module">
  import mkparse from '';


Comment Parser

Build Status npm version Coverage Status

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.


npm i mkparse --save

For the command line interface install mkdoc globally (npm i -g mkdoc).


Parse a string or buffer:

var mkparse = require('mkparse')
  , stream = mkparse.parse('/**Compact comment*/');
stream.on('comment', function(comment) {

Load and parse file contents:

var mkparse = require('mkparse')
  , stream = mkparse.load('index.js');
stream.on('comment', function(comment) {

Parse and write comment data to file as newline delimited JSON:

var mkparse = require('mkparse')
  , fs = require('fs')
  , stream = mkparse.load('index.js').stringify();

Use a language pack:

var mkparse = require('mkparse')
  , stream = mkparse.parse(
      '# @file spec.rb', {rules: require('mkparse/lang/ruby')});
stream.on('comment', function(comment) {

Combine language pack rules:

var mkparse = require('mkparse')
  , stream = mkparse.parse(
      '; ini style comment\n# shell style comment',
      {rules: [require('mkparse/lang/ini'), require('mkparse/lang/shell')]});
stream.on('comment', function(comment) {

For more detail see the api docs.


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


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 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.


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.


Usage: mkparse [options] <files...>

  Parse source file comments.

  -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




Created by mkdoc on April 18, 2016