JavaScript is an extremely expressive language which is often difficult to describe in terms of meta data and fields. Often, important information that needs to be documented just doesn't fit into a neat, tidy spot.
joDoc uses markdown as its core to provide simple, human-readable docs which it converts to HTML.
Basically, anything that ends up in an <h1> tag becomes a keyword that:
- appears in the keyword index
- is turned into a link wherever it is used in your documentation text
- resolves in the TOC into links
Markdown supports inline HTML, so your code comments and markdown files may have arbitrary bits of HTML in them.
joDoc also supports HTML files, so you can use it to bring together docs built from other tools. The autolink feature works at the HTML level, so by just including HTML files in your doc project, they become linkable from other document pages automatically.
jsdoc in its various incarnations and some of its spawn like yuidoc take the approach that "what is good for Java is good for JavaScript". All these flavors are based on javadoc formatting, and have been in use for some time.
Aside from the regimented markup being a bit odd to read (admit it, even Java developers don't love it), it suffers from an inflexibility with regard to all the coding patterns available with JavaScript. Basically, it fails due for the same reason that all JavaScript libraries which attempt to subvert JavaScript's natural object model fail. These solutions, while influential in the idea that some form consistent coding approach could help us make better code, are not in the spirit of embracing JavaScript.
Why then do so many developers continue to use a documentation tool which was born of the same well-meaning yet misguided logic of "let's pretend JavaScript is Java"?
Excellent effort, but complex to set up and also tries to make a regimented system for documenting source code. It is extendable, but again, we have a documentation solution which is trying to force JavaScript into a more limited set of features.
For those who want more insight into how the documentation is created:
for each markdown file in your project,
convert to an HTML file
for each source file,
produce a markdown file from all text between `/**` and `*/` comments
convert the markdown file into an HTML file
for each HTML file,
for each `h1` tag,
add an `id` field based on the contents of the `h1` tag
add contents to a `file.html#id` keyword index
for each HTML file,
for each keyword in our index,
intelligently wrap the keyword with an `a` tag
that points to the `file.html#id` from our keyword index
produce an index:
sort the keyword index
save the keyword index as an HTML file
save the keyword index as a JSON file
produce a table of contents:
build sections based on directory names
retain sorted directory order
save as a JSON file
save as a formatted HTML file
concat all html files into one document:
structure:
header
table of contents
contents from all html files, in order
sorted keyword index
footer
convert all fixed paths to local references:
(e.g. `filename.html#about` becomes simply `#about`)
This produces a bundle of files which can be used a couple of ways:
-
A loose set of files which is used by the joDoc application (written using the jo library, of course)
-
An alternative "single page" view of all the documentation (which some people really like)
-
Your own collection of files with some other organization means (which is trivial to do with pre-rendered HTML and the JSON document structure).