Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
117 lines (83 sloc) 3.77 KB

About joDoc

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.

Autolinker

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

Injecting HTML Snippets

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.

Comparison

vs. jsdoc

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"?

vs. Natural Docs

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.

joDoc Process

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:

  1. A loose set of files which is used by the joDoc application (written using the jo library, of course)

  2. An alternative "single page" view of all the documentation (which some people really like)

  3. Your own collection of files with some other organization means (which is trivial to do with pre-rendered HTML and the JSON document structure).