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

docflux

v1.1.2

Published

Stream jsdoc block to json object and markdown

Downloads

19

Readme

docflux Build Status NPM version

Stream source code documentation block to json object

Features

Api

Install the module with: npm install docflux

var docflux = require('docflux');

process.stdin(docflux())
  .on('data', function(jsdoc) {
    console.log(JSON.stringify(jsdoc, null, 2))
  })

Yield (see docflux json object below)

{"token": "MyClass#foo(a,b,[c])", "description": "...", "tags": [{...}]}
{"token": "MyClass#bar(a,b,[c])", "description": "...", "tags": [{...}]}

Command line tool

Install the command line tool with: npm install -g docflux

Usage: docflux docflux <file>

Options:

  -h, --help          output usage information
  -V, --version       output the version number
  -m --markdown       Output a markdown formated documentation (default to json)
  -o --output <file>  Output to this file
  -i --indent [size]  Indent json output
  -d --depth  <size>  Minimal header depth for markdown output

# Pipe to another json consumer
cat input.js | docflux | consumejson

# Use input and output
docflux input.js -o output.md

# Or write markdown output ...
docflux --markdown input.js > output.md

# Or write json output with indentation...
docflux input.js -i 4 > output.json

Supported comments style

Docflux support most of the jsdoc-like simple doc-block (see tests for more examples)

Short & compact doc-block style

/**
 * Create new user
 * Long description of this method
 * @param {String} name User name
 * @param {String|String[]} groupId Group id or array of group id
 * @param {Object} [options]
 * @returns {Boolean}
 */
 MyClass.prototype.createUser(name, groupId, options) { //...

Long doc-block style

/**
 * Create new user
 *
 * Long description of this method with list and examples
 *
 *   - Do this
 *   - And this
 *
 * Example:
 *
 *     var my = new MyClass();
 *     my.createUser('Foo',['admin','staff'], { silent: true });
 *
 * @param {String} name
 *        Username with some restrictions
 *        - Must be lower-case
 *        - Must be funny
 *
 * @param {String|String[]} groupId Group id or array of group id
 *        Put some markdow here too:
 *
 *            // Example
 *
 * @param {Object} [options]
 *   Options are always optional
 *   but params description alignement is based on first line indentation
 *
 * @returns {Boolean}
 *
 * @thows {InvalidUsernameException} Not funny (maybe)
 *
 * @see http://www.gelule.net/
 *
 * @memberOf MyClass
 */
      createUser: function(name, groupId, options) { //...

Output examples

docflux.markdown()

Opinionated stream that transform a docflux stream to markdown (see markdown output example) (nb: this is more a demo usage of docflux's json stream)

var docflux = require('docflux');

process.stdin(docflux())
  .pipe(docflux.markdown())
  .on('data', function(jsdoc) {
    console.log(JSON.stringify(jsdoc, null, 2))
  })

@memberOf tag

The @memberOf associate a backbone-like method with a class.

var MyClass = ClassCreator({
  /**
   * Create new user
   * @memberOf MyClass
   */
   createUser: function () { //...
})

Yield the following docflux.signature (with markdown transform):

## MyClass#createUser()

Add a dot to the memberOf tag (@memberOf MyClass.) to force a static method signature:

## MyClass.createUser()

docflux json object

For each jsdoc-style block in the source code, docflux provide a pojo javascript object with those fields:

  • token: The documented function or class or method
  • params: Formated parameters list (expl: a, b, [options])
  • memberOf: According to the @memberOf tag if present, the class of the currently documented method. Useful with backbone-like code (expl: MyClass)
  • signature: A formated signature (expl: MyClass#foo(a, b, [options]))
  • description: The full description part of the doc-block comment
  • summary: Only the summary part of the doc-block comment
  • body: The extended description part of the doc-block comment
  • tags: An array of tag object with:
    • type: The tag name
    • types: Array of types (for tags like @param {Object|String})
    • token: The param token (for @param {Type} token)
    • description: The full tag description
    • summary: Only the summary part of the description (first line)
    • body: The extended part of the tag description
    • raw: The raw tag extracted from the doc-block comment
  • flags: An array of all tags name (type): can be used as flag to check a tag presence
  • isClass: True if this comment concern a Class (see isClass())
  • isFunction: True if this comment concern a function
  • isExports: True if this comment concern a module.exports
  • ignore: a @ignore tag exists
  • firstLine: The first line of code used to generated the token
  • raw: The full raw doc-block

Why another dox (and credit)?

  • Docflux was inspired by dox and dox is widely used with many other projects based on it: so consider using it if it match your needs
  • Docflux is a one-day project to provide
    • A stream interface
    • Less verbose and opinionated output (no pre-formated html output)
    • Support for multiline tag description
  • Docflux output is partially compatible with dox output
  • Sometimes, reinventing the wheel opens new perspectives (sometimes not...)

License

The MIT license (see LICENSE.md)