Overview
This grunt module was build to generate :
- Classic javascript documentation from http://usejsdoc.org/ comment.
- Rest API documentation based on http://apidocjs.com/ comment
How to install
npm install --save-dev yocto-doc
How to configure
In you Gruntfile.js add this :
'use strict';
module.exports = function (grunt) {
// Project configuration.
grunt.initConfig({
// Default package
pkg : grunt.file.readJSON('package.json'),
// Define yocto doc config
yoctodoc : {
options : {
api : true // To generator API documentation
},
all : [ 'PATH_OF_YOUR_JS_FILE' ]
}
});
// Load npm task
grunt.loadNpmTasks('yocto-doc');
grunt.registerTask('doc', [ 'yoctodoc' ]);
};
How to use
grunt doc
Output
- Classic Javascript documentation : by default this documentation was exported into docs/jsdoc directory.
- API Rest documentation : by default this documentation was exported into docs/api-doc directory.
API generator usage
@apiSchema
By default yocto-doc generate doc from api-doc comment tag, but those tags must not be defined in your classic javascript comment.
We do this just to keep a clean code comment, because api-doc comment can be huge and long to write.
At this point you must use the @apiSchema
tag to defined the path of your api-doc definition.
For example :
/**
* A huge and long classic comment
*
* @param {String} a a description
* @param {String} b b description
* @return {String} return description
*
* @apiSchema path_to_your_api_doc_schema_definition.js
*/
During the process yocto-doc will try to load all of your schema and build the doc from this definition.
@apiHeader and @apiFooter
By default api-doc provide a header
and footer
configuration, but this configuration must be set on a apidoc.json
file at the root of your projet.
With yocto-doc your can set it on your classic javascript comment just after @apiSchema tag.
For example :
/**
* A comment
*
* @class
* @public
*
* @apiSchema path_to_your_api_doc_schema_definition.js
* @apiHeader {YOUR_HEADER_TEXT_TITLE}(path_to_your_header_content.md)
* @apiFooter {YOUR_FOOTER_TEXT_TITLE}(path_to_your_footer_content.md)
*/