doxie-core

The heart of http://npm.im/doxie.

The CLI program doxie claims to be “the simplest docs generator you’ve seen”. doxie-core is the heart of doxie, so it’s inherently very simple.

All it does is take an array of data and pipe it through a bunch of plugins (functions). Just keep in mind that most plugins will expect dox-compatible data. That’s it.

See for yourself:

Demo

Let’s see what happens without any plugins to pipe through:

import doxie from 'doxie-core'
 
const doxComments = [
  {isPrivate: false},
  {isPrivate: true},
  {isPrivate: false},
];
 
doxie([])(doxComments);
 
//» {docs: [
//»   {data: {isPrivate: false}},
//»   {data: {isPrivate: true}},
//»   {data: {isPrivate: false}},
//» ], version: 1}

Simple, but not very useful. Let’s try filtering that data:

const myFilter = ({data}) => !data.isPrivate;
 
doxie([
  require('doxie.filter')(myFilter),
])(doxComments).docs;
 
//» [
//»   {data: {isPrivate: false}},
//»   {data: {isPrivate: false}},
//» ]

Fair enough. But the whole business is about outputting docs for humans. Let’s try that then:

let counter = 1;
const myTemplate = ({data}) => ({data,
  output: `${data.isPrivate ? 'Private' : 'Public'} comment ${counter++}\n`
});
 
doxie([
  require('doxie.filter')(myFilter),
  require('doxie.template')(myTemplate),
  require('doxie.output')(),
])(doxComments).output;
 
//» "Public comment 1
//» Public comment 2
//» "

Installation

$ npm install doxie-core

API

doxie-core(plugins, [{stdout, stderr}])
  → pipeline(data)

Parameters:

• plugins ^{Function[]}
  An array of plugin functions. You can pick one of the ready-made plugins or write your own.

• [options.stdout] ^{{Writable Stream}}
  If set, the output of each plugin will be written to this stream.

• [options.stderr] ^{{Writable Stream}}
  If set, the error of each plugin will be written to this stream.

Return value:

• pipeline(data) ^{Function}
  A function composed of plugin functions. Feed it an array of data (like the one that comes out of dox.parseComments). It’ll be passed to plugins – they’ll deal with it.

Writing a plugin

Every plugin for doxie is a function. The functions are composed with one another to form a functional pipeline. To give you an idea of this, these are roughly equivalent:

$ doxie --plugin1 --plugin2 --plugin3

require('doxie-core')([
  require('doxie.plugin1')(),  // Returns a plugin function.
  require('doxie.plugin2')(),  // Returns a plugin function.
  require('doxie.plugin3')(),  // Returns a plugin function.
]);

require('doxie-core')([
  ({docs, version}) => {
    require('doxie.plugin3')()(
      require('doxie.plugin2')()(
        require('doxie.plugin1')()(
          {docs, version}
        )
      )
    )
  },
]);

Heads up! doxie-core is a very simple, slim system. We give a lot of power to plugin authors. But beware! With power comes responsibility. When writing a plugin make sure you know the rules and keep to them. You can easily break other plugins otherwise.

Here’s the signature your plugin function should match:

plugin({docs, version})
  → {docs, version, [output], [error]}

Parameter properties:

The input object is passed directly by doxie-core if the plugin is first in the plugin pipeline. Otherwise it’s the output of the former plugin.

• chunks
  type: Object[]
  An array of docs. Every doc is a part of the documentation. It can either:

  • correspond to dox output for a single comment; or
  • be generated by a plugin – such as a description for a group of comments.

• [docs[].data]
  type: Object
  doc.data is populated if the doc corresponds to an item of the input array – a dox comment fed into doxie. This object is immutable and should be copied directly to the corresponding output doc.data.

• [docs[].output]
  type: String
  doc.output is populated if other plugins have generated output for this doc.

• version
  type: Number
  The exact number 1. We pass it so you can make sure that your plugin is compatible with the input it receives.

Returned properties:

The output object is processed by doxie to produce side-effects – and passed unchanged as input to the subsequent plugin.

You’ll probably find yourself returning an object similar to the input object, changing just a couple of properties. Don’t be tempted to change the object though. This is the only single copy of the data, and access to it might still be needed by other plugins. Always return a new object. You can use Object.freeze to protect yourself from other plugins mutating your object.

• docs
  type: Object[]
  The array of docs. See the input docs property for more info.

• [docs[].data]
  type: Object
  Make sure you copy the data from the corresponding input doc. doxie doesn’t need it, but you may break subsequent plugins if you don’t.

• [docs[].output]
  type: String
  The rendered text output of this doc.

• version
  type: Number
  The exact number 1.

• [output]
  type: String
  If the stream stdout is defined, output will be written to it. Keep in mind that node’s process.stdout only accepts strings.

• [error]
  type: String
  If the stream stderr is defined, error will be written to it. Keep in mind that node’s process.stderr only accepts strings.

License

MIT © Studio B12 GmbH