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.
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 path
specify a path to where you want doc files placed
--toc file
joDoc 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 file
tells joDoc to use a specific markdown parser.
--title string
is an optional title which will appear on your HTML output.
--template file
tells joDoc to use a custom HTML file as a template, a simple example:
<html><head><title>$title</title></head>
<body>$body</body></html>--smartypants
tells joDoc to use a specific smartypants prettifier.
-s
tells joDoc to filter output through SmartyPants.
tidy
tells joDoc to use the HTMLTidy prettifier.
htmltidy string
tells joDoc to use a specific HTMLTidy compatible prettifier
filespec
is 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:
jodocBy 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/docsSpecifying files to parse:
jodoc ABOUT.mdown *.js *.cssDefining a table of contents structure:
jodoc --toc ~/release.tocBuilding 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.