Documenting Javascript with Code Illuminated

How to quickly add good-looking documentation to small bits of Javascript code

During my (various) years as a web developer I have written mostly Python code. However, this does not constitute the totality of the code I've written: in fact, I happen to write also some Javascript code almost on a daily basis (although not as much as Python).

code_illuminated.jpegFor a long time, I have neglected my Javascript code, mostly due to the fact that, every time I wrote something in Javascript, I felt I was producing a half-assed hack instead of a good piece of software.

This induced me into a big error that I came to regret later: not documenting my code at all[1].

Is it that bad?

Yes. Atleast for me, Javascript development, with its heavy use of closures, anonymous functions, asyncronous callbacks and the like, makes it quite hard (for me) to understand the Javascript code I've written later on. Or maybe I just write crappy code, but even if I take that for granted, either I change job or I still have a problem.

To give an example of how bad it can be, I had once to solve a bug on some code I had written years before: after spending a day trying to figure out why it worked at all, I ended up using the next day rewriting it (with the new functionality and bugs fixed) because it was just easier than spend another n days trying to figure out what the code was doing.

And that's when I decided that I had to document my Javascript code.

The quest for a tool

Therefore I started looking around for possible tools. I initially started out with JSDoc, but it was more painful than helpful: I kept forgetting the correct keywords, and where I had to put them (@class being the most annoying: I had things that behaved like classes, but no real class definition).

What I really wanted was something like Python's docstrings, that allowed me to write free-form "hints" about what a certain function or object method was doing, that understood minimal markup, and that allowed me, at times, to add more extensive documentation about a whole module (like how the logic flowed and so on).

My requirements were:

  1. A tool to mostly document at the function level (or object or method-level): I did not need a tool to write high-level documentation because there was no real need for it (the Javascript itself was more a collection of small tools than a full-blown, cohesive application)
  2. A tool that allowed me to embed documentation within the source, so that it was easy for me to maintain it along the code
  3. Something that produced good-looking documentation, and was easy, almost effortless, to use (and having a "compilation" step does not make it easy, because you then either forget to compile or you end up with Makefiles, both of which I wanted to avoid)

Code Illuminated

That's when I discovered Code Illuminated, a project started by someone at Mozilla and that at the time was still looking maintained (nowadays it isn't, atleast judging from its original website).

I started using it and it felt quite awesome. After seeing it was largely abandoned, I started making small modifications by myself, adding a few small features I needed, and went along this way for some time.

Recently, however, I felt it was quite selfish for me to do so (in reality, it was plain lazyness) and I decided to put it on GitHub and "maintain" it.

It's three pages you've been reminiscing about your life, now would you please show us something?

Woops, sorry, I got carried away. I blame Proust.

So, here's how you document Javascript code with Code Illuminated, at last.

First thing off, you must actual write the documentation inside your Javascript files: this is done by using line comments (those with //):

/* 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);

The markup is done using WikiCreole, which is a markup whose existence I was previously unaware of, but works well enough[2].

Then you download the tarball of Code Illuminated and you unzip it in the same directory where you put all your Javascripts (make sure to get rid of the intermediate directory that GitHub creates), and then you create (in the same directory) an 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" 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>

Make sure to substitute the link href from #foo.js to #<name_of_my_file>.js and it works!

The resulting documentation is something aking to Code Illuminated own documentation (this thing is self documenting, rawr!).

I recommend you to read the rather comprehensive README and... happy documenting!


[1] To be fair, I did put some comments here and there, but in the end they were of little help once I had forgotten how the whole thing flew.

[2] But I'll be adding Markdown soon

Share this on

Share |

On same topics

Comments

comments powered by Disqus