AtomDoc CLI
An example of the command line tool reporting an issue and a verbose output. The source of the fixture is here.
A JS lib and command line tool to check for missing AtomDoc information in a javascript project.
It inspects js code for functions and methods looking for things like parameters and return statements then compares that information against the AtomDoc comments. It highlights potentially missing information and can be used as part of build validation (like linting or automated tests) in a continuous integration setup like Travis CI.
AtomDoc is a comment documentation format, created by GitHub. It is based on markdown, which for many teams, is easier to adopt than more complex formats. Take a look at GitHub's maximal example for a quick guide on how to use it.
You can also look at the source code of this project to find examples like this one:
/** * Public: constructor for AtomDocDocument instance. * * * `content` * * ## Examples * * ```js * const content = fs.readFileSync(filepath, 'utf-8'); * const doc = new AtomDocDocument(content); * ``` */ { thiscontent = content; } /** * Public: parses javascript document defined by `this.filepath`. * * ## Examples * * ```js * const content = fs.readFileSync(filepath, 'utf-8'); * const doc = new AtomDocDocument(content); * doc.process().then(result => { * result.parserResult; * result.inspectorResult; * }); * ``` * * Returns */ { const commentParser = ; const contentParser = thiscontent commentParser; const contentInspector = thiscontent; ; return PromiseallcontentParserpromise contentInspectorpromise; }
Installation
To use the cli just install globally via npm:
$ npm install -g atomdoc-cli
To use as the js api save the install in your project via npm:
$ npm install --save atomdoc-cli
Usage
CLI
The help has the basic information for using the command line tool:
$ atomdoc -h Usage: atomdoc <file> A CLI interface
--output-path
The output-path
flag will write the inspection and parser report to a json file.
$ atomdoc ./test/fixtures/class.js --output-pathFile ./api.json written.
You can also specify the filename/path:
$ atomdoc ./test/fixtures/class.js --output-path report.jsonFile report.json written.
--reporter
The default reporter is basic_reporter
. It will be used if no reporter is specified:
$ atomdoc ./test/fixtures/class.js./test/fixtures/class.js Container.list line 9Examples: Missing Add `## Examples` to public methods
You can write your own reporter. It just needs to be a function that expects the results
{Result} and showAll
[{Bool}] as parameters.
You can also pass in a package name that's installed in the node_modules directory.
--verbose
If you want to see passing results as well as errors, just include the verbose
flag; otherwise it just shows the failing results.
$ atomdoc ./test/fixtures/class.js./test/fixtures/class.js Container.list line 9Examples: Missing Add `## Examples` to public methods
With the verbose flag:
$ atomdoc ./test/fixtures/class.js -v./test/fixtures/class.js Container.list line 9Name: listClass: ContainerArg Count: 1Arg Name: valReturn: trueExamples: Missing Add `## Examples` to public methods
JS API
This can also be used as a javascript library.
var AtomDocDocument = ; const doc = content;doc;
NPM Script and Continuous Integration
It can also be used as a code verification tool with continuous integration workflow like Travis CI.
This project uses it right next to eslint and ava tests to validate the build:
In the package.json
you can add it like this:
"scripts": ,
In the .travis.yml
you can configure the validation:
language: node_jsnode_js: "6"script: - npm run validate