Code Illuminated is a library that helps in documenting Javascript code.
It allows the developer to write documentation inside the source file, by placing it inside comments, in a manner very similar to JSDoc.
However, unlike these solutions, it does not mandate a very strict syntax, allowing the user to mix in narrative documentation with the documentation of single functions, objects or methods.
Code Illuminated also provides a two paned visualization of the file, with the documentation on the left and the code being documented (which has been modified to incorporate proper spacing) on the right.
Documentation is written using the WikiCreole markup.
This library is recommended for writing mid-level or low-level documentation aimed at developers: for high-level or user documentation, it is better to use other tools like Sphinx.
- Easy to get started with
- Thanks to the documentation being inlined with code, it makes the documentation maintenance easier
- Looks good
- Doesn't need any compilation step
- Makes it easy to provide documentation alongside source
- Works gret for small bits of Javascript, or mid-sized projects where documenting the API is sufficient
Using Code Illuminated is very simple. Let's start by taking an example Javascript file and add documentation within line comments (those beginning with two slashes, //).
/* file: foo.js (not parsed by Code Illuminated) */
(function($) {
// = Foo =
//
// Lorem ipsum dolor sit amet, consectetur adipiscing elit.
// Maecenas et euismod nisi. **Aliquam euismod** congue diam et iaculis.
//
// Nunc vitae ante nec sem sagittis lobortis id placerat nisl.
window.Foo = {
// == Foo.bar(eggs) ==
//
// Spammifies {{{eggs}}}
bar: function(eggs) {
return "We have spam, spam, spam and "+eggs;
}
};
})(jQuery);Note: line comments that are further indented than the original line-indented documentation block (the header) will not be parsed.
After documenting our Javascript file, we create an index HTML file:
<!DOCTYPE html>
<!-- file: index.html -->
<html>
<head>
<link rel="stylesheet" type="text/css"
href="google-code-prettify/prettify.css" />
<link rel="stylesheet" type="text/css"
href="docs.css" />
<title>Foo</title>
</head>
<body>
<div id="content">
<div id="overview" class="documentation" style="display: none;">
<h1>Foo</h1>
<p>The documentation for <em>Foo</em>.</p>
<ul>
<li>
<a href="#foo.js">foo.js</a>
</li>
</ul>
</div>
</div>
<script type="text/javascript"
src="jquery-1.7.2.js"></script>
<script type="text/javascript"
src="wikicreole.js"></script>
<script type="text/javascript"
src="google-code-prettify/prettify.js"></script>
<script type="text/javascript"
src="docs.js"></script>
</body>
</html>It is important that:
- You create a div id="content" as root element
- That within the content div you create a div id="overview" class="documentation" style="display: none;"
- That you place a link to the file(s) containing documentation as they were anchors (e.g. href="#foo.js")
And that we include following CSS at the top:
- google-code-prettify/prettify.css (which is the standard Google prettify CSS)
- docs.css
And these Javascripts at the bottom:
- jquery-1.7.2.js (could be any jQuery from 1.4 onwards)
- google-code-prettify/prettify.js (again, standard Google prettify from distribution)
- wikicreole.js
- docs.js
We now only have to serve index.html via HTTP and visit it with our browser.
Code Illuminated itself is docuemnted this way: you can see the full documentation online and take a look at its source.
Within the documentation, it is possible to add links to various headers within the same file or other files.
For example, if in our example above we wanted to link to the Foo.bar() function from within foo.js, we could add a link as follows:
// See [[#foo.js@Foo.bar(eggs)|Foo.bar(eggs)]] for more details.
The link is a standard Creole link, but the target is peculiar and is writted in the format:
#<target_file.js>@<title_of_header>
Where <target_file.js> is the Javascript file where the heading we want to link to is located, and <title_of_header> is the exact text that is found in the heading.
Note: the linking works only for headings, not for bold or italics elements.
Interwiki links are a feature of Creole.
They are expressed as [[WikiName:WikiPage]]: WikiName is looked up in the list of configured wikis and a URL is obtained (therefore a mapping between wiki names and base URLs exists), to which WikiPage is appended.
Code Illuminated comes with a set of predefined wikis:
| Wiki name | Associated URL |
|---|---|
| WikiCreole | http://www.wikicreole.org/wiki/ |
| Wikipedia | http://en.wikipedia.org/wiki/ |
| MDNJavascript | https://developer.mozilla.org/en/JavaScript/Reference/ |
| MDNCSS | https://developer.mozilla.org/en-US/docs/CSS/ |
| MDN | https://developer.mozilla.org/en/ |
It is however possible to add further wikis by adding a Javascript inline block at the end of index.html and doing:
<script type="text/javascript"> window.code_illuminated.CREOLE.interwiki['MyWiki'] = 'http://example.com/'; </script>
The original code was developed for Mozilla Corporation and has seen contributes from:
- Atul Varma <atul@mozilla.com>
- Sander Dijkhuis <sander.dijkhuis@gmail.com>
- Alberto Santini <albertosantini@gmail.com>
- Simone Deponti <simone.deponti@abstract.it>