selfDoc.js: JavaScript that Documents Itself

Thanks to its interpreter, JavaScript can coerce functions to strings. These strings can be used as documentation. selfDoc.js is a JavaScript function that takes a function or object literal (containing a JavaScript application built in a modular style) and returns an object that describes the application's API. This can be combined with a templating tool (lm.js, perhaps) to produce a dynamic HTML document.

var test = function () {
    // A function that does nothing
  };
  test.subFunction = function () {
    // Another useless function
  };
  selfDoc("Test", test, "A test application using selfDoc.js");
  // Returns an object describing the app
  /**
  {
    appName: "Test",
    comment: ["A function that does nothing"],
    overview: "A test application using selfDoc.js"
    properties: [{
      name: "subFunction"
      comment: ["Another useless function"],
      implementation: "function () { ... }"
    }]
  }
  */

The documentation is refreshed every time selfDoc is called. selfDoc can be kept alongside unit tests or demos providing a dynamic set of documentation that is always up to date. Combine the resulting object with your favorite templating tool and you have dynamic HTML documentation. The comments are only extracted from the first continuous block (at the top of each function).

selfDoc is low on dependencies, a browser is the only requirement. selfDoc coerces the public/current-scope functions to strings, extracting their comments (FireFox/JaegerMonkey removes comments at run time, so functionality is hampered here).

There are numerous alternatives. The majority are designed to be added into a build process, such as Maven or ant. Typically they are written in a language other than JavaScript, requiring a development environment with these tools/languages installed. These may be more appropriate to large projects with established build systems.

There are alternatives that also have native JavaScript implementations, docco looks particularly tasty.

Get selfDoc.js from GitHub

Tagged JavaScript documentation
​