Chalkboard

A small node package parsing source code and generating simple documentation

@chalk overview
@name Chalkboard.js

@description
"Chalkboard is a documentation generator and it started as a generator for Coffeescript. Docco is great but it is very simple. This project took inspiration from JSDoc to parse Coffeescript better for documentation. Chalkboard allows user to indicate variable types, function parameters, return variables and much more.

Although it is originally written for parsing Coffeescript, it can be updated to parse other languages. Currently, it can generate documentation from Coffeescript and Javascript.

(quotes are only added around this block to make prettify render this better, it's not needed)"

@url https://github.com/adrianlee44/chalkboard
@license MIT
                    

How to use this?

  1. Install Chalkboard with npm:
    sudo npm install -g chalkboard
  2. Comment your code with supported tags and add @chalk to the beginning of each comment block
  3. Run it against any files:
    chalkboard -j DOC.md src/
  4. If you use Grunt:
    npm install grunt-chalkboard

Example

Chalkboard's README is generated with Chalkboard

Supported Tags

  • @name - Name of the file, function, variable
  • @description - A summary/description
  • @author - Author of the file
  • @email - Email of the author
  • @copyright - Copyright information
  • @url - Project URL
  • @license - Software license for the code
  • @enums - Document object property
  • @since - Time when this is created
  • @param - Parameter of a function
  • @callback - Callback function type
  • @function - Document function
  • @returns - Return value of a function
  • @variable - Document variable
  • @deprecated - Function/variable no longer available
  • @version - Version of the code
  • @access - Access level of the variable
  • @private - Private shortcut for access
  • @public - Public shortcut for access
  • @dependencies - Document all dependencies
  • @example - Document example code

Command line interface

Usage: chalkboard [options] [FILES...]

Options:

  -h, --help           output usage information
  -V, --version        output the version number
  -o, --output [DIR]   Documentation output file
  -j, --join [FILE]    Combine all documentation into one page
  -f, --format [TYPE]  Output format. Default to markdown (markdown | html)
  -p, --private        Parse comments for private functions and variables
  -h, --header         Only parse the first comment block
                    

Public API

chalkboard = module.exports = {
  parse,
  compile,
  format,
  write,
  processFiles,
  configure
}
                    

TODO

  • Implement @default tag
  • Implement @type tag
  • Implement configuration for different languages
  • Add unit tests
  • Module system for generating different output format
  • Implement inline tags