PDoc: Document Generation for Prototype.js based Javascript

by jl2 on July 6th, 2009

I’ve been going through the process of documenting our mSpace 2.0 Javascript client in such a way that API documents are built automatically. The codebase is Prototype based Javascript so I needed something that supports that style of Javascript.

Initially I tried JSDoc, which whilst good didn’t handle advanced Prototype.js Object Orientated constructs very well.

After some research I found that the Prototype.js developers themselves were in the process of moving to a documentation tool called PDoc for their 1.6.1 release. PDoc is different to JSDoc in that it doesn’t make any attempt to parse the Javascript itself, instead it relies purely on information provided within specially crafted comments.

PDoc’s online documentation is terrible, especially for a Ruby newbie (PDoc requires Ruby to run) so here are the steps I took to get PDoc working on a RedHat Linux install (step 1&2 via LinuxWebLog):

  1. Install ruby rpms via yum:
    # yum install ruby ruby-libs ruby-mode ruby-rdoc ruby-irb ruby-ri ruby-docs
  2. Download and install rubygems from rubygems.org.
    Change to the extracted directory and run:

    # ruby setup.rb
  3. Download the libraries needed for PDoc from rubygems
    # gem install rake BlueCloth treetop
  4. Download PDoc from github http://github.com/tobie/pdoc/tree/master
  5. You need to edit the Rakefile to point to the Javascript file you wish to produce documentation for. To do this, edit the line that looks like:
    source = File.expand_path(File.join(File.dirname(__FILE__), "directory", "subdirectory", "all.js"))

    Each parameter in quotes is a part of the path relative to the current Rakefile, so the above example would be looking for the file:

    ./directory/subdirectory/all.js

    Note: The mSpace2.0 client is built from a number of separate files so in order to get this to work with PDoc I had to write a short PHP script to concatenate all the files into one.

  6. To build the documentation you then just need to execute:
    # rake doc

I came across a few issues when using PDoc, here are some of the workarounds I found:

  1. PDoc comments must start at the beginning of the line, any whitespace before the leading /** and the parser will not pick up the comment
  2. Always put an empty line between any function declaration and its description, eg:
    /**
     *  InformationControl#setParam(key, value) -> undefined
     *  - key (String): the key for the parameter
     *  - value (String): the value for the parameter
     *
     *  Sets a parameter
     **/

    not:

    /**
     *  InformationControl#setParam(key, value) -> undefined
     *  - key (String): the key for the parameter
     *  - value (String): the value for the parameter
     *  Sets a parameter
     **/
  3. You can make text in the descriptions link to Object references by using [[Object]] notation, eg:
    /**
     * Tells the [[ColumnView]]'s subview (normally a [[ListView]]) to scroll to the specified row
     **/
  4. Example code can be given – just indent the line by atleast 4 spaces (wraps text in a <pre> tag)
  5. A horizontal line can be indicated by 3 hyphens:
    /**
     * ---
     **/
Share and Enjoy:
  • email
  • Print
  • Twitter
  • del.icio.us
  • Facebook
  • Digg
  • Technorati
  • StumbleUpon
  • Slashdot
  • Ping.fm
  • LinkedIn
  • Google Bookmarks
  • MySpace
  • Netvibes
  • Reddit
  • Tumblr

From Javascript

1 Comment
  1. Hi Ben, I am tying to do a simple proargm written in Ruby. Here is what I want to accomplish.1. user input the extension and get that input, assigned it to a variable myvar 2. check to see if myvar is a valid extension.I have created 2 extension on FreePBX (200 and 201), my problem is that I don’t know what variable name is holding the 200 and 201 or Are all the extension that I created on FreePBX goes to a database if so, What is the name of the database and how can I access it. That is why I can’t validate if myvar is a valid extension. Pardon me for bothering you again and I don’t know if I can ask question like this on your blog. Thanks.

Leave a Reply

Note: XHTML is allowed. Your email address will never be published.

Subscribe to this comment feed via RSS