JSODoc—JavaScript Outlining Documentor

© 2010-2011, Martin Rinehart


Download JSODoc

Introduction

I was used to JavaDoc comments in my Java. I wanted something similar, but lighter, for my JavaScript. I googled for a solution. Got some answers, but mostly was told that nothing has caught on for JavaScript. So I decided to write something: JSODoc.

Design goal 1: I wrote it in JavaScript, so other JavaScripters can modify it to meet their needs.

Design goal 2: A JavaScripter should be able to master JSODoc in a minute or two.

The Basic JSODoc Comment

You use the basic JSODoc comment within the <script> section(s) of an HTML file, or anywhere in a .js file. Most commonly, it caps var declarations, function declarations and object property assignments. These are some examples, followed by the JSODoc they generate.

/**1 Outline Comment, Explained Soon */

/** This is a var declaration. */
var foo = init_val;

/** This is a function declaration. */
function bar() { ... }

/** Here is an object property assignment. */
prop: prop_value,

   2 1. Outline Comment, Explained Soon
   4     a) foo - This is a var declaration.
   7     b) bar() This is a function declaration.
  10     c) prop: Here is an object property assignment.

Note the bit of punctuation after function and property names, separating them from var names.

You may add as many more lines to your JSODoc comment as you need to do justice to the thing you are documenting. Only the first line will appear in the outline. I think a full sentence is a good thing.

You may add JSODoc comments anywhere else. The comment will appear in the outline, but it will not be numbered. (Like a little vertical whitespace? /** */ will do the trick.)

The Outline JSODoc Comments

JSODoc outline comments follow the /** with an additional single letter based on the classic outline hierarchy Miss Foggybottom taught you in grade school.

/**I Main Topic */
/**A Subtopic */
/**1 Sub-Subtopic */
/**a Sub-Sub-Subtopic */

If you JSODoc the above, it comes out like this:

   2 I. Main Topic
   3   A. Subtopic
   4     1. Sub-Subtopic
   5       a) Sub-Sub-Subtopic 

I suggest you capitalize most first letters as if these are topic headings (which they are). If you have a compound modifier, like "Second-Level", the letter after the hyphen is capitalized, too.

Note, you do not count. /**2 is NOT a JSODoc comment. Use as many /**1 comments as you like. JSODoc will count and do the appropriate outline thing for you. This makes it dead simple to add and delete JSODoc outline comments.

An Example

/**I Namespace Wrapper */

/** The only global. */
function martins_namespace() {

/** */

/**I Contents of the Namespace */

  /**A Important Stuff */

    /** Big deal function. */
    function bigDeal() { ... }
    /** Self-important var. */
    var imIportant;

  /**A Unimportant Stuff */

    /** Minor function. */
    function notImportant() { ... }

    /** Simple object. */
    var simple = {
      /** Single property. */
      married: false
        }
} // end of martins_namespace

    martins_namespace();

The above code and JSODoc will generate this outline:

   2 I. Namespace Wrapper
   4   A. martins_namespace() The only global.

   9 II. Contents of the Namespace
  11   A. Important Stuff
  13     1. bigDeal() Big deal function.
  15     2. imIportant - Self-important var.
  18   B. Unimportant Stuff
  20     1. notImportant() Minor function.
  23     2. simple - Simple object.
  25     3. married: Single property.

One Last Feature

If you do this without backing up, you must think I'm a better coder than I think I am.

Where should you put your JSODoc? In the file it documents, of course. If you use the Text output style and your file has the right comment, you get a second output textarea that features your original file with the JSODoc inserted where your special comment specifies. Use one of the following comment/close pairs. Note that the comment and the close must be flush left, exactly as shown.

HTML (not in script):

<!-- Table of Contents
-->

.js:

/* Table of Contents
*/

You can follow the "Table of Contents" with whatever you choose. A backlink to this article would be nice.

<!-- Table of Contents ( http://MartinRinehart.com/frontend-engineering/tools/jsodoc_doc.html )
-->

The first time you JSODoc this, the outline is inserted into the Table of Contents comment. The second time you do it, JSODoc decides that you want to replace an out-of-date Table of Contents, and does so.

You just Select All and Copy from the "New File" textarea, then Select All, Paste over your file in your code editor. If you do this without backing up first, your hard work will always be lost. Murphy's Law has not been repealed. If you are backed up this should work easily and save you lots of time.

Warning! The JSODoc program uses two passes. Inserting the outline invalidates all the line numbers (unless the new outline is identical in length to the old one). JSODoc copies the first pass's output back into the Input textarea and runs a second time to get the line numbers right. The content of the Input area is not what you pasted.

Running JSODoc

When you "download" JSODoc, you are opening an HTML page. It will appear in your browser as if you have started a program. Ignore it. Save As ... someplace that will be handy while you are JavaScripting.

Assuming you choose jsodoc.html for the file name, open jsodoc.html in your text editor. Select All, Copy. Open jsodoc.html in a browser (if it's not alreay open) and paste it into the input textarea.

Note: jsodoc.html is fully JSODoc commented. In fact, more than fully. Verbosely. Wastefully. OK, it's supposed to demo itself. Look at the generated outline and look at the source if there's anything you don't understand.

Fixup Button

A complete waste; ignore it. (Or continue here.) The default tab in a textarea is eight spaces. Looking at my ever-so-carefully indented code with eight-space tabs drives me crazy. This converts the tab character to four space characters.

Output Buttons

Text is the most common choice. Experiment with the others. Text is the only one that creates the New File textarea with the outline inserted for you.


Download JSODoc

Feedback is welcome: MartinRinehart at gmail dot com

# # #