npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

docblock-parser

v1.0.0

Published

A standalone docblock parser

Downloads

4,878

Readme

docblock-parser Build Status

A line based doc block parser.

Motivation

I wasn't able to find a standalone, not opinionated docblock parser. Most parsers seem to make fixed assumptions about the value of a tag. This is a slightly less opinionated parser. It allows you to specify which parts of a tag make up its value, on a line basis.

Quick example

> var docblockParser = require('docblock-parser');
> docblockParser.parse('/** @type {Object} */');
{ text: '',
  tags: { type: '{Object} Description' } }

Terminology

The parser is built around the idea of consuming lines. If the parser encounters a line that starts with a tag pattern (@tagname), it delegates the consumption of the following lines to a tag specific consumer or the default consumer. If the line doesn't start with a tag, it delegates to the text consumer.

A consumer is a function that accepts a Docblock object and returns a value which is associated with the tag or free text.

A Docblock object is just a stack of lines, with which a consumer can .peek() at the current line or .pop() it from the stack to consume it. A consumer .pop()s lines until a condition is met (or there no lines left).

Install

npm install docblock-parser

API

docblockParser.parse(docstring)

This parses docstring with the default configuration (defaultConfig.js) which provides sensible defaults for jsdoc tags.

docblockParser(config).parse(docstring)

Allows you to specific your own consumers and tags.

config.docBlockPattern

Type: RegExp

The pattern to validate a docblock. Defaults to /^\/\*\*|^\s*\* ?/m.

config.startPattern

Type: RegExp

The start of docblock. The match will be removed before parsing. Defaults to /^\s*\/\*\*\s?/.

config.endPattern

Type: RegExp

The end of docblock. The match will be removed before parsing. Defaults to /\*\/\s*$/.

config.linePattern

Type: RegExp

Start of a line in a docblock. The match will be removed while parsing aline. Defaults to /^\s*\* ?/.

config.text

Type: function

A consumer for all free text inside the doc block. I.e. text not associated with a specific tag.

config.default

Type: function

The fallback consumer used for tags not listed in config.tags.

config.tags

Type: object

A tag name -> consumer mapping that allows to use different strategies for different tags.

Returns {text: (Array|string), tags {tagname: (Array|?), ...}}
text

Is an array if the doc block contains multiple sections of free text, else a single string.

tags

Is an object of tagname -> value mappings. The type of the value depends on the consumer being used for the tag, but it will definitely be an array if the tag appeared multiple times in the doc block (e.g. @param).

Examples

Custom Tags

var docblockParser = require('./');
var docstring = [
  '/**',
  ' * Some free text',
  ' *',
  ' * @public',
  ' * @extends',
  ' * SuperLongClassName',
  ' * @multiline-example',
  ' * E.g. for example code',
  ' *',
  ' *     var foo = bar;',
  ' *',
  ' * With description.',
  ' *',
  ' * @param {string} foo',
  ' * @param {number} bar',
  ' * @returns {boolean} Some desciption',
  ' */',
].join('\n');

// config.text and config.default is provided through the default config
var result = docblockParser({
  tags: {
    public: docblockParser.booleanTag,
    extends: docblockParser.singleParameterTag,
    'multiline-example': docblockParser.multilineTilTag,
    param: docblockParser.multilineTilTag,
    returns: docblockParser.multilineTilTag,
  }
}).parse(docstring);

returns

{
  text: 'Some free text',
  tags: {
    public: true,
    extends: 'SuperLongClassName',
    'multiline-example': 'E.g. for example code\n\n    var foo = bar;\n\nWith description.',
    param: [ '{string} foo', '{number} bar' ],
    returns: '{boolean} Some desciption'
  }
}

Note that there is no line break after "Some free text" and "With description". If you are using the built-in default consumer (consumeTil)(which all of the built-in consumer do), leading and trailing lines will be removed form the value.

In this example we specified our own tag consumers. We could have also used the default ones and just called docblockParser.parse(docstring).

Custom format

var docblockParser = require('./');
var docstring = '{##\nSome free text\n@memberOf test\n##}';
var result = docblockParser({
	docBlockPattern: /\{##([^#]*)##\}/ig,
	startPattern: /^\s*\{##\s?/,
	endPattern: /##\}\s*$/
}).parse(docstring);

returns

{
  text: 'Some free text',
  tags: {
    memberOf: 'test'
  }
}

Built-in consumers

The parser comes with consumers for the most common use cases:

  • multilineTilTag

  • Consumes as many lines until it encounters a line starting with the @tagname` pattern.

  • Returns: The collected lines. This is usually the safest to use, since it may not always be possible to format the values of tags in a specific way.

  • multilineTilEmptyLineOrTag

    • Consumes as many lines until it encounters an empty line or a tag.
    • Returns: The collected lines.
  • booleanTag

    • Consumes just the current line.
    • Returns: True. The mere fact that the function is called means that the tag exists.
  • singleParameterTag

    • Consumes lines until it finds a non-empty line.
    • Returns: The collected line. That is the value of the tag.
  • multiParameterTag(delimiter)

    • Based on multilineTilEmptyLineOrTag
    • Returns: Returns an array of values. The values come from multilineTilEmptyLineOrTag split by delimiter.

License

ISC