doxie --filter

A plugin for doxie.
Filter comments through a custom function.

Note: Don’t panic. doxie --filter is a flexible, low-level plugin. We’re working on higher-level plugins which you can drop into your project without fiddling with configuration.

CLI Usage

doxie --filter is a plugin for the command-line tool doxie. Most plugins are designed for dox data. Install all three if you haven’t already:

$ npm install --global dox doxie doxie.filter

Pass the option --filter to doxie to put the plugin in your pipeline. By default it will import the filter function from <pwd>/.doxie.filter.js and pipe your docs through it:

$ dox | doxie --filter

You can also specify a custom file to import the filter function from:

$ dox | doxie --filter ./build/my-custom-filter.js

Programmatic usage

doxie.filter can be used directly with doxie-core – the backend of doxie. Install both if you haven’t already:

$ npm install doxie-core doxie.filter

Pass the filter function directly as a parameter:

const doxie = require('doxie-core');
const filter = require('doxie.filter');
const myDoxData = {/* … */};
 
doxie([
  filter(({data}) => (!data || !data.isPrivate)),
])(myDoxData);

The filter function

Put the file .doxie.filter.js in the root directory of your project and export a single function from it. Every doc will be piped through your filter function. If it returns a truthy value, the doc will be kept. Otherwise it won’t be passed down the plugin pipeline.

Here’s a drop-in example written in ES5:

// `/.doxie.filter.js`
 
module.exports = function(doc) {return (
  // Keep the doc if it has no associated data (comes from a plugin, not from
  // a comment)
  !doc.data ||
 
  // Or if *dox* hasn’t marked it as private.
  !doc.data.isPrivate
);};

Signature:

filterFunction({[data], [output]})
  → keep?

Input properties:

• [data] ^{*}
  The data associated with a doc. If the doc corresponds comes from a dox comment, this will be the output from dox.

• [output] ^{String}
  The rendered text output for a doc.

Return value:

• keep? ^{Boolean}
  If falsy, the doc won’t be passed down the plugin pipeline.

License

MIT © Studio B12 GmbH