joDoc is a plain text code documentation scheme for JavaScript. It was created out of frustration felt working with various documentation systems available. joDoc does not attempt to perform any special automation other than generating links, table of contents, an index, and of course rendered HTML for your documentation.
This is a simple example of what you can do in your source documentation. This is all free-form markdown text.
/**
myClass
=======
This is my class. It rocks, and this is its _description_, which also
rocks.
Extends
-------
- someOtherClass
Methods
-------
- setName(name)
Where `name` is a `String`.
Use
---
// here is some sample code which shows how to use this class
var x = new myClass(name);
> Note: use of the `name` reserved word is probaly a bad idea.
*/
You can put your comments for your code either:
-
in your source code (anywhere and in as many pieces as you want) denoted with
/** ... */multiline-comment blocks -
separate markdown (
*.mdown) files, probably (tho not necessarily) named to match your JavaScript files
Can't get much more flexible than that.
- perl 5.8 or greater (YMMV with older perl versions)
- Markdown.pl (or compatible parser)
- SmartyPants.pl (optional)
Windows users should get some suggestions for installing ActiveState or cygwin
jodoc [--output path] [--title string] [--toc file] [--template file] [--markdown file] [-s] [--smartypants file] [filespec]
-
--output pathspecify a path to where you want doc files placed
-
--toc filejoDoc will work with a table of contents structure defined in a markdown file. Your TOC file can be completely manual, just a list of atuo-linked terms (or markdown or even HTML style links), but joDoc will do do more if you want it. For example:
Developer Guide --------------- - {ABOUT.mdown} - {README.mdown} - {docs/} - {LICENSE.mdown} API Reference ------------- ### Core - {js/core} ### Data - {js/data} ### User Interface - {js/ui}You can put a file path inside the {} pairs, and joDoc will attempt to find and sort all the headers from the files which match that pattern.
NOTE: the TOC is not a replacement for the
filespecin the command line. You need to make sure to tell joDoc what directorie(s) to parse. The TOC is a semi-automated document which can be useful but is not required.
-
--markdown filetells joDoc to use a specific markdown parser.
-
--title stringis an optional title which will appear on your HTML output.
-
--template filetells joDoc to use a custom HTML file as a template, a simple example:
<html><head><title>$title</title></head> <body>$body</body></html> -
--smartypantstells joDoc to use a specific smartypants prettifier.
-
-stells joDoc to filter output through SmartyPants.
-
tidytells joDoc to use the HTMLTidy prettifier.
-
htmltidy stringtells joDoc to use a specific HTMLTidy compatible prettifier
-
filespecis one or more files to parse. Directories will be recursively handled.
Note: No support for STDIN input at the moment. Use named pipes for now. Also, block devices like
/dev/randomare totally untested.
Simple case:
jodoc
By default, joDoc will start in the current directory and recursively look for
*.mdown, .*.js and *.css files to build documentation. Unless directed
otherwise, joDoc will print a unified HTML file on standard out with all the
documentation output, and an index of all <h1> tags.
Specifying an output base directory:
jodoc --output /var/www/html/docs
Specifying files to parse:
jodoc ABOUT.mdown *.js *.css
Defining a table of contents structure:
jodoc --toc ~/release.toc
Building joDoc's documentation with joDoc:
jodoc --output html -s --toc samples/TOC_SAMPLE.mdown *.mdown
cp samples/css/* html/
cp samples/index.html html/
Note that the css and index.html step is specific to this documentation set; it is not necessarily required for the docs in your project.