JSDog README

Summary

JSDog only supports a minimal subset of JSDoc tags, works only at a very coarse resolution, and (for now) is intended only to help provide basic in-browser class API documentation & regression testing.

Input source files are broken up and parsed in blocks, where a "block" is essentially just a multi-line javascript comment. Inline comments for property tagging is also supported.

Motivation

Like dox*, jsdog was meant to be a quick jsdoc replacement that doesn't require java. Dox didn't quite fit my needs and I'd been looking for an excuse to build my first non-trivial node.js module.

In addition, jsdog includes jQuery's Qunit to provide regression testing and makes the test results available alongside generated documentation.

• https://github.com/visionmedia/dox

Installation

Should just be a simple npm install jsdog

Required Modules

NPM should take care of getting these setup for you if you don't already have them:

• jade
• nopt (should come with npm)

Usage

Usage: jsdog [options]

Options:
  -v                               verbose logging (loglevel 2)
  --help, -h                       this screen
  --ignore, -i                     ignore extraneous newlines in comments
  --loglevel <number>              set logging level (0-3)
  --template <path>, -m <path>     path to the jade output template
  --source <path>, -s <path>       source file to document
  --tests <path>, -t <path>        qunit tests file
  --title <string>, -n <string>    documentation title

Formatters

Each line in a javascript comment block may contain the following basic text formatters:

Example                     Description
--------------------------  ------------------------------------------------------------------------
*Bold*                      enclose text in asterisks
!Italic!                    enclose text in exclamations
_Underline_                 enclose text in underscores
--Smaller--                 enclose text in double-minusses
++Larger++                  enclose text in double-plusses
^Superscript^               enclose text in carets
[red[simple colors]         enclose text in square brackets, add left hand square bracket with color
[green|black[ dual color ]  same as above, but separate foreground and background colors with a pipe

Examples

• The current JSDog documentation at http://psema4.github.com/JSDog/
• There is a Hello World project in the examples folder which should help get you started

Multiple Files

To process all javascript files in the current folder, run jsdogs and tell it where you want the generated docs to go:

jsdogs /var/www/docs/

Qunit test files should have the same filename as the associated source file but in a t/ folder, or in the current folder with the filename prefixed by 'tests-'

eg. foo.js will check for tests-foo.js and ./t/foo.js

Tag Implementation Status

Supported

Meta

• @author
• @version

Code

• @constructor
• @deprecated
• @event
• @function
• @name
• @param
• @private
• @property
• @protected
• @public
• @returns
• @this
• @throws

Credits

• Intended tag support derived from the jsdoc-toolkit wiki: http://code.google.com/p/jsdoc-toolkit/wiki/TagReference
• jQuery & Qunit for optional unit tests: http://docs.jquery.com/Qunit
• SyntaxHighlighter3 for, well, syntax highlighting: http://alexgorbatchev.com/SyntaxHighlighter/
• The sprintf function from the PHP.js project is used in logging: http://phpjs.org/