logicaroma
10/13/2011 - 9:59 AM

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

Set of gists for implementing jsdoc reporting in maven. from and using jsdock (http://code.google.com/p/jsdoctk-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. 

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

{{{
USAGE: java -jar jsrun.jar app/run.js [OPTIONS] <SRC_DIR> <SRC_FILE> ...

OPTIONS:
  -a or --allfunctions
          Include all functions, even undocumented ones.

  -c or --conf
          Load a configuration file.

  -d=<PATH> or --directory=<PATH>
          Output to this directory (defaults to "out").

  -D="myVar:My value" or --define="myVar:My value"
          Multiple. Define a variable, available in JsDoc as JSDOC.opt.D.myVar.

  -e=<ENCODING> or --encoding=<ENCODING>
          Use this encoding to read and write files.

  -E="REGEX" or --exclude="REGEX"
          Multiple. Exclude files based on the supplied regex.

  -h or --help
          Show this message and exit.

  -n or --nocode
          Ignore all code, only document comments with @name tags.

  -o=<PATH> or --out=<PATH>
          Print log messages to a file (defaults to stdout).

  -p or --private
          Include symbols tagged as private, underscored and inner symbols.

  -q or --quiet
          Do not output any messages, not even warnings.

  -r=<DEPTH> or --recurse=<DEPTH>
          Descend into src directories.

  -s or --suppress
          Suppress source code output.

  -S or --securemodules
          Use Secure Modules mode to parse source code.

  -t=<PATH> or --template=<PATH>
          Required. Use this template to format the output.

  -T or --test
          Run all unit tests and exit.

  -u or --unique
          Force file names to be unique, but not based on symbol names.

  -v or --verbose
          Provide verbose feedback about what is happening.

  -x=<EXT>[,EXT]... or --ext=<EXT>[,EXT]...
          Scan source files with the given extension/s (defaults to js).

}}}

==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:

{{{
<plugin>
        <groupId>nl.windgazer</groupId>
        <artifactId>jsdoctk-plugin</artifactId>
        <version>[VERSION]</version> <!-- Set this to the current version!! -->
</plugin>
}}}

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.

{{{
<plugin>
        <groupId>nl.windgazer</groupId>
        <artifactId>jsdoctk-plugin</artifactId>
        <version>[VERSION]</version> <!-- Set this to the current version!! -->
        <configuration>
                <srcDir>${basedir}/src/main/webapp</srcDir>
                <recurse>5</recurse>
        </configuration>
</plugin>
}}}


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

{{{
<plugin>
        <groupId>nl.windgazer</groupId>
        <artifactId>jsdoctk-plugin</artifactId>
        <version>[VERSION]</version>
        <configuration>
                <template>jsdoc</template> <!-- Alternatives are not pre-installed for version 2.x-->
                <directory>${project.build.directory}/jsdoc</directory>
                <recurse>1</recurse>
                <ext>js</ext>
                <allfunctions>true</allfunctions>
                <Allfunctions>false</Allfunctions>
                <privateOption>false</privateOption>
                <!-- If you're using the maven default setup this alternative is sometimes required
                to make the plugin work: ${basedir}/src/main/webapp/ -->
                <srcDir>${basedir}/src/main/webapp</srcDir>
                <exclude><!-- Since jsdoctk 2.3.2 -->
                        <param>regularexpression</param><!--Multiple param entries allowed-->
                </exclude>

        </configuration>
</plugin>
}}}

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.

= 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'.