POD-like documentation for JavaScript: Doc::Simply

grink on 2008-10-09T05:06:09

I've just released Doc::Simply, a tool for generating documentation from JavaScript (or C, C++, etc.) comments.

I use it to for my b9j documentation

The idea came to me while developing some JavaScript: I was craving a way to drop in free-form documentation in a .js file as easily as I could in a .pm with perlpod.

The Doc::Simply format is modeled after Plain-Old-Documentation, but it is not an exact mimic. Body formatting, for example, is in Markdown (no C<>, L<>, ...)

However, if you are craving pure POD, then it shouldn't be too difficult to bolt a proper parser/generator on top of Doc::Simply

You can run it from the command-line as doc-simply

doc-simply < source.js > documentation.html

doc-simply --help

An example:
   /*
    * @head1 NAME
    *
    * Calculator - Add 2 + 2 and return the result
    *
    */

   // @head1 DESCRIPTION
   // @body Add 2 + 2 and return the result (which should be 4)

   /*
    * @head1 FUNCTIONS
    *
    * @head2 twoPlusTwo
    *
    * Add 2 and 2 **and** return 4
    *
    */

   function twoPlusTwo() {
       return 2 + 2; // Should return 4
   }

/*
 * @head1 AUTHOR
 *
 * Alice <alice@example.com>
 *
 * [http://example.com](http://example.com)
 *
 */



... which will generate this document

You can download it from http://search.cpan.org/CPAN/authors/id/R/RK/RKRIMEN/Doc-Simply-0.02.tar.gz

... or install it via cpan:

cpan -i Doc::Simply

POD-like documentation for JavaScript: Doc::Simply