Set of gists for implementing jsdoc reporting in maven. from and using jsdock (http://code.google.com/p/jsdoctk-plugin/)

ConfigPluginSpace.wiki

Introduction

Running jsdoctk plugin without changing your project pom. Sometimes I want to run jsdoc for a project just so that I can get some quick information on the used javascripts, but I don't want to stick another dependency in the pom of the project. Because I kept running into this when working only for a single short task on big projects I went and figured out how to configure maven to include jsdoctk-plugin in its' list of 'known plugins'.

Details

When you know what to do, it turns out to be really simple. All you have to do is add a few lines of xml to your 'settings.xml' which can be found in your 'user-directory'. On unix-like machines this would be at '~/.m2/settings.xml'.

Add the following xml:

 {{{
  <pluginGroups>
    <pluginGroup>nl.windgazer</plugingroup>
  </plugingroups>
 }}}

And make sure you have at least version 2.0.1-RC1 of jsdoctk-plugin installed in maven2. Now all you have to do is go to your project-base and run ' *mvn jsdoctk:jsdoc* ' and presto! Because I introduced commandline configuration in 2.0.1-RC1 you can modify the defaults of the plugin without configuring your pom too. Just use the following set of parameters:

 {{{
   jsdoc.tempdir
   jsdoc.directory
   jsdoc.srcdir
   jsdoc.template
   jsdoc.extension
   jsdoc.recurse
   jsdoc.allfunctions
   jsdoc.privateoption
 }}}

With a default web-project structure you would get a good result using 'mvn jsdoctk:jsdoc -Djsdoc.recurse=5'.

Configuring.wiki

A quick and dirty guide on how to configure the jsdoctk-plugin for 2.3.2

As I think it would be foolish to try and explain options that already have a usable documented explanation I will start by printing the JSDoc Toolkit's --help output. I will follow with the maven configuration counterparts, all of these are directly linked to the command-line options as they are internally simply expanded, converted and used as the arguments for running the toolkit. Truly the only difference being that the toolkit will not be started from command-line but instead will be 'invoked' from another Java application within an alread running JVM.

The JSDoc Toolkit usage:

As of 2.3.2, usage is

The jsdoctk-plugin options:

The default JSDoc-plugin configuration, help is exluded (of course) and the long-names of the properties are used. All you should need to run jsdoctk reports is the following configuration:

The most common cause of this plugin not generating anything useful is that the recursion isn't set high enough. Although I understand I could simply set the default higher, I'd rather people are aware of this option as it could potentially generate a significant performance increase, depending on the amount of files in your project. The main two options you should be aware of are therefor 'srcDir' and 'recurse'. Set 'srcDir' to correctly identify your javascript root if you have a lot of files in your webapp directory, set 'recurse' to dig deep enough if your don't mind the performance hit while building.

The full set of available options (and their default values) are configured as follows:

Currently some support has been added for some of the new settings exposed in JSDoc Toolkit 2, none are essential. The --exclude option has been added, with support for multiple entries. For future reference, I will be looking into supporting at least some of the new features and would appreciate any feedback on which would be preferable.

mvn-jsdock-plugin

# Installing jsdock plugin. (http://code.google.com/p/jsdoctk-plugin/wiki/InstallationInstructions)
 mvn install:install-file -DgroupId=nl.windgazer -DartifactId=jsdoctk-plugin -Dversion=2.3.2 -Dfile=./jsdoctk-plugin-2.3.2.jar -DpomFile=./jsdoctk-plugin-2.3.2.pom

# Configuring POM plugin 
 <plugin>
        <groupId>nl.windgazer</groupId>
        <artifactId>jsdoctk-plugin</artifactId>
        <version>2.3.2</version>
        <configuration>
            <recurse>3</recurse><!-- This is the *level of recursion*, not a boolean -->
        </configuration>
    </plugin>

# Starting the jsDoc
 After configuring the plugin to your liking you can simply run JSDoc Toolkit by invoking 
 *'mvn jsdoctk:jsdoc'*, for the *'build'* phase. Or simply build your site using the *site:site* goal when
 you've configured the plugin in the reporting plugins.