Awesome
xplain
Generates API documentation / markdown inserts from unit tests
This is still very early release, probably would not work right away for your needs.
xplain takes unit tests and generates documentation examples. Check out the reverse: jsmd takes code blocks in Markdown and runs them as unit tests.
inputs
src/add.js
/**
Adds two numbers
@method add
*/
function add(a, b) { return a + b; }
test/add.js
/** @sample add */
QUnit.test('adds numbers', function () {
QUnit.equal(add(2, 3), 5);
});
usage
xplain -i src/add.js -i test/add.js
produces HTML documentation:
add Adds two numbers
add(2, 3); // 5
See the generated example api
To see (the very few) command line options run xplain
or xplain -h
command.
Updating Markdown doc
xplain can update code blocks inside a Markdown file (like this doc) with unit tests marked using @sample. If we have:
// add.js
/** @sample add */
gt.test('basic addition', function () {
gt.equal(add(1, 2), 3, '1 + 2 = 3');
gt.equal(add(100, -100), 0, '100 + -100 = 0');
});
// README.md
#### basic addition
add(10, 20); // 30
then command xplain -i add.js -o README.md
will update README.md and it will have:
// README.md
#### basic addition
add(1, 2); // 3
add(100, -100); // 0
This feature makes the package's top level README.md file a great place to provide lots of examples, without needing a separate API docs. It can be also used to unit test blog posts.
Details
Stop writing unmaintainable source samples inside the help comments using @example tag. Instead tag your unit tests with @sample or @example tag and they will be included in the generated API documentation.
The test code will be intelligently transformed into human readable format. QUnit and gt test syntax is supported. If the code cannot be transformed, it will be displayed in its original form. qunit is assumed by default, specify an alternative using -f command line option, for example -f gt.
Multiple documentation levels
There are 4 levels of details captured in the API.
- Method description from jsdoc comments
- Sample source code transformed from the unit tests and displayed under the method
- Unit test source code tagged @example can be displayed by clicking on the toggle
- Finally the original function source code can be shown by clicking on the source button.
Supported frameworks
- QUnit
- gt
- Jasmine/Mocha/Bdd
console.assert
statements- lazy-ass assertions
Inspiration
There are several API examples that I found particularly useful.
- lo-dash and underscore APIs are beautiful and extremely easy to use.
- tooltipster gently introduces its features from basic use to more advanced.
- AngularJs shows end to end unit test source as an example. The source code is not transformed from its original BDD Jasmine (?) style.
New @- tags
xplain uses two new custom jsdoc tags:
- @sample - transforms the unit test that follows into human readable form and displays the code block right under the method's description.
- @example - displays the unit test only when clicked on the button with the test's name.
Example
/** @sample Arrays/first */
QUnit.test(function () {
QUnit.equal(_.first([5,4,3,2,1]), 5, 'returns first element');
QUnit.deepEqual(_.first([1,2,3], 2), [1, 2], 'can pass an index to first');
});
will be transformed into
_.first([5, 4, 3, 2, 1]); // 5
_.first([1, 2, 3], 2); // [1,2]
If a unit test has a name, it will be displayed above the transformed code.
Known issues
On some systems, OS wildcard expansion can be misleading. For example on Windows when using Git bash shell, when calling using -i foo/*.js the shell will expand wild card to match the FIRST file only. If you find that wildcard is not working as correctly, please switch the slash direction. For example -i foo\*.js
3<sup>rd</sup> party libraries
- lo-dash is used throught the code to deal with collections. This library was the inspiration for this project, because it has an excellent API documentation.
- dox together with some custom glue parses JSdoc style comments.
- check-types is used to verify arguments through out the code.
- esprima and escodegen are used to parse and reformat unit test code in human readable form.
- js-beautify is used for final example code formatting.
- jQuery is used to drive UI in the generated HMTL documentation.
- google-code-prettify is used to syntax highlight code samples in the generated documentation.
- moment.js is used for date and time manipulation.
- optimist is used to process command line arguments. I tried to use commander.js, but it had problems grouping multiple arguments into arrays.
- background pattern is the source for the background pattern.
- glob is used to find input source files using wildcards.
- allong.es provides convenient functional bits and pieces.
- intro.js was used to create the feature tour
- pithy is used to programmatically generate the output HTML.
- html is used to beautify the output HMTL (tabs and stuff).
- mkdirp simplified folder creation.
- fs.extra simplified usual file operations (file copy, move).
- tooltipster is used in the generated API page to display tooltips.
- marked to parse optional header markdown document to place in the output.
Small print
Author: Gleb Bahmutov © 2014
License: MIT - do anything with the code, but don't blame me if it does not work.
Spread the word: tweet, star on github, etc.
Support: if you find any problems with this module, email / tweet / open issue on Github
MIT License
Copyright (c) 2014 Gleb Bahmutov
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.