Merge e02dfa1 into 07bf3fe

Readme.md

@@ -64,19 +64,19 @@ Let’s see what happens without any plugins to pipe through:
 ```js
 import doxie from 'doxie-core'
 
-const myData = [
+const doxComments = [
   {isPrivate: false},
   {isPrivate: true},
   {isPrivate: false},
 ];
 
-doxie([])(myData);
+doxie([])(doxComments);
 
-//» [
+//» {chunks: [
 //»   {data: {isPrivate: false}},
 //»   {data: {isPrivate: true}},
 //»   {data: {isPrivate: false}},
-//» ]
+//» ], version: 1}
 ```
 
 
@@ -86,8 +86,8 @@ Simple, but not very useful. Let’s try filtering that data:
 const myFilter = ({data}) => !data.isPrivate;
 
 doxie([
-  (comments) => comments.filter(myFilter),  // ☆ http://npm.im/doxie.filter
-])(myData);
+  require('doxie.filter')(myFilter),
+])(doxComments).chunks;
 
 //» [
 //»   {data: {isPrivate: false}},
@@ -99,21 +99,19 @@ doxie([
 Fair enough. But the whole business is about outputting docs for humans. Let’s try that then:
 
 ```js
-let count = 0;
-const myTemplate = (data) => (
-  `${data.isPrivate ? 'Private' : 'Public'} n° ${++count}\n`
-);
+let counter = 1;
+const myTemplate = ({data}) => ({data,
+  output: `${data.isPrivate ? 'Private' : 'Public'} comment ${counter++}\n`
+});
 
 doxie([
-  (comments) => comments.filter(myFilter),
-  (comments) => comments.map(({data}) => ({data, output: myTemplate(data)})),
-    // ☆ http://npm.im/doxie.template
-  (comments) => comments.map(({output}) => output || '').join(''),
-    // ☆ http://npm.im/doxie.to-string
-])(myData);
-
-//» "Public n° 1
-//» Public n° 2
+  require('doxie.filter')(myFilter),
+  require('doxie.template')(myTemplate),
+  require('doxie.output')(),
+])(doxComments).output;
+
+//» "Public comment 1
+//» Public comment 2
 //» "
 ```
 
@@ -130,10 +128,103 @@ $ npm install doxie-core
 
 
 
-Usage
------
+<a                                                                 id="api"></a>
+API
+---
+
+<h3                                                     id="api/signature"><pre>
+doxie-core(plugins, [{stdout, stderr}])
+  → pipeline
+</pre></h3>
+
+<h5                                                         id="api/parameters">
+Parameters:
+</h5>
+
+* **`plugins`**
+  <sup>{Function[]}</sup>  
+  An array of plugin functions. You can pick one of the [ready-made plugins][] or [write your own][].
+
+* **`[options.stdout]`**
+  <sup>{Writable Stream}</sup>  
+  If set, the `output` of each plugin will be written to this stream.
+
+* **`[options.stderr]`**
+  <sup>{Writable Stream}</sup>  
+  If set, the `error` of each plugin will be written to this stream.
+
+[ready-made plugins]:  https://www.npmjs.com/browse/keyword/doxie-plugin
+[write your own]:      #writing-a-plugin
+
+
+
+
+<a                                                    id="writing-a-plugin"></a>
+Writing a plugin
+----------------
+
+Every plugin for *doxie* is a function. Here’s the signature it should match:
+
+<h3                                        id="writing-a-plugin/signature"><pre>
+plugin({chunks, version})
+  → {chunks, version, [output], [error]}
+</pre></h3>
+
+
+<h5                                                 id="writing-a-plugin/input">
+Input object properties:
+</h5>
+
+The input object is passed directly by *doxie-core* if the `plugin` is the first in the functional pipeline. Otherwise it’s the output of the former plugin.
+
+* **`chunks`**
+  <sup>{Object[]}</sup>  
+  An array of `chunk`s. Every `chunk` 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.
+
+* **`[chunks[].data]`**
+  <sup>{Object}</sup>  
+  `chunk.data` is populated if the chunk 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 `chunk.data`.
+
+* **`[chunks[].output]`**
+  <sup>{String}</sup>  
+  `chunk.output` is populated if other plugins have generated output for this chunk.
+
+* **`version`**
+  <sup>{Number}</sup>  
+  The exact number `1`.
+
+
+<h5                                                id="writing-a-plugin/output">
+Output object properties:
+</h5>
+
+The output object is processed by *doxie* to produce side-effects – and passed unchanged as input to the subsequent plugin.
+
+* **`chunks`**
+  <sup>{Object[]}</sup>  
+  The array of `chunks`. See the input `chunks` property for more info.
+
+* **`[chunks[].data]`**
+  <sup>{Object}</sup>  
+  Make sure you copy the `data` from the corresponding input `chunk`. *doxie* doesn’t need it, but you may break subsequent plugins if you don’t.
+
+* **`[chunks[].output]`**
+  <sup>{String}</sup>  
+  The rendered text output of this chunk.
+
+* **`version`**
+  <sup>{Number}</sup>  
+  The exact number `1`.
+
+* **`[error]`**
+  <sup>{*}</sup>  
+  If `stderr` is defined, `error` will be written to `stderr`.
 
-…
+* **`[output]`**
+  <sup>{*}</sup>  
+  If `stdout` is defined, `output` will be written to `stdout`.
 
 
 

module/index.js

@@ -3,8 +3,12 @@ const identity = require('1-liners/identity');
 
 export default (plugins) => {
   const transform = plugins.reduce(pipe, identity);
-  return (input) => {
-    const inputData = input.map((data) => ({data}));
-    return transform(inputData);
+  return (doxOutput) => {
+    const input = {
+      chunks: doxOutput.map((data) => ({data})),
+      version: 1,
+    };
+
+    return transform(input);
   };
 };

package.json

@@ -26,6 +26,7 @@
   , "nodangel": "1.3.8"
   , "tap-spec": "2.2.2"
 
+  , "object-assign": "3.0.0"
   , "tape-catch": "1.0.4"
   }
 

test.js

@@ -1,48 +1,60 @@
-const test = require('tape-catch');
-
 import doxie from './module/index';
 
+const test = require('tape-catch');
+const assign = require('object-assign');
+
 test('Does what the demo says', (is) => {
-  const myData = [
+  const doxComments = [
     {isPrivate: false},
     {isPrivate: true},
     {isPrivate: false},
   ];
 
   is.deepEqual(
-    doxie([])(myData),
-    [
+    doxie([])(doxComments),
+    {chunks: [
       {data: {isPrivate: false}},
       {data: {isPrivate: true}},
       {data: {isPrivate: false}},
-    ],
+    ], version: 1},
     'without any plugins to pipe through'
   );
 
   const myFilter = ({data}) => !data.isPrivate;
 
   is.deepEqual(
     doxie([
-      (comments) => comments.filter(myFilter),
-    ])(myData),
+      (input) => assign({}, input, {chunks:
+        input.chunks.filter(myFilter),
+      }),  // ☆ http://npm.im/doxie.filter
+    ])(doxComments).chunks,
     [
       {data: {isPrivate: false}},
       {data: {isPrivate: false}},
     ],
     'filtering data'
   );
 
-  const myTemplate = ({data}, index) => ({data,
-    output: `${data.isPrivate ? 'Private' : 'Public'} n° ${index + 1}\n`
+  let counter = 1;
+  const myTemplate = ({data}) => ({data,
+    output: `${data.isPrivate ? 'Private' : 'Public'} comment ${counter++}\n`
   });
 
   is.deepEqual(
     doxie([
-      (comments) => comments.filter(myFilter),
-      (comments) => comments.map(myTemplate),
-      (comments) => comments.map(({output}) => output || '').join('')
-    ])(myData),
-    'Public n° 1\nPublic n° 2\n',
+      (input) => assign({}, input, {chunks:
+        input.chunks.filter(myFilter),
+      }),
+
+      (input) => assign({}, input, {chunks:
+        input.chunks.map(myTemplate)
+      }),  // ☆ http://npm.im/doxie.template
+
+      (input) => assign({}, input, {output:
+        input.chunks.map(({output}) => output || '').join('')
+      }),  // ☆ http://npm.im/doxie.to-string
+    ])(doxComments).output,
+    'Public comment 1\nPublic comment 2\n',
     'outputting docs for humans'
   );