Using JSeqUnit

JSeqUnit provides a taglet to include sequence diagrams in JavaDoc documentation. As it depends on tools.jar of the JDK, it is necessary to set the JAVA_HOME variable to your JDK directory to run this taglet.

Running JavaDoc with the JSeqUnit taglet from command line

To use the taglet it is necessary to pass the JavaDoc executable the following parameters:

  • '-taglet net.sf.jsequnit.javadoc.SequenceTaglet'
    instructs JavaDoc to use the JSeqUnit taglet
  • '-tagletpath path/to/compiled/classes;path/to/compiled/test/classes;lib/jsequnit-2.0.jar';lib/junit-4.10.jar;lib/jseq-0.6.jar;lib/sdedit-light-3.1.jar'
    indicates where to find the jar file containing the classes of JSeqUnit. Additionally, this information is used to setup the environment for the JUnit test execution to trace method calls and generate sequence diagrams. The compiled classes of the sequence tags are necessary to execute for the tracing of the method calls. The JUnit tests provide the environment for the method calls. The libraries are used by JSeqUnit itself.

Other parameters of JavaDoc or the standard doclet can be used together with JSeqUnit (see JavaDoc documentation) - e.g.

  • '-d output/directory'
    specifies the target directory, where the JavaDoc output and the sequence diagram images are placed
  • '-sourcepath source/directory'
    tells, where to look for source code files that should be parsed
  • '-classpath lib/junit-4.10.jar'
    if you are generating JavaDoc documentation for JUnit test classes, it is necessary to have JUnit in the classpath, because the JavaDoc tool requires access to all libraries from which annotations are used (e.g. @Test from JUnit)

Example

When the following command is executed

    javadoc 
      -taglet net.sf.jsequnit.javadoc.SequenceTaglet 
      -tagletpath target/classes;target/test-classes;target/jsequnit-2.0.jar;target/lib/junit-4.10.jar;target/lib/jseq-0.6.jar;target/lib/sdedit-light-3.1.jar 
      -sourcepath src/site/example/main
      -d target/test-dir
      -subpackages net.sf.jsequnit.example

the JavaDoc command runs successfully.

Using the taglet with Maven

Add the maven-javadoc-plugin together with the taglet configuration to run JSeqUnit with maven.

Please note that you must compile your project (the classes and the test classes) first, before running the maven-javadoc-plugin

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
        <executions>
      	  <execution>
            <id>generate-javadoc</id>
            <phase>site</phase>
            <goals>
              <goal>javadoc</goal>
            </goals>
            <configuration>
              <taglet>net.sf.jsequnit.javadoc.SequenceTaglet</taglet>
              <tagletArtifact>
                <groupId>net.sf.jsequnit</groupId>
                <artifactId>jsequnit</artifactId>
                <version>2.0</version>
              </tagletArtifact>
              <tagletPath>${project.build.outputDirectory};${project.build.testOutputDirectory}</docletPath>
            </configuration>
          </execution>
        </executions>
      </plugin>

Using the taglet with Eclipse

  1. Right-click on a Java project.
  2. Use 'Export ...' togehter with 'Java > Javadoc'.
  3. Put the configuration of the JSeqUnit taglet into 'Extra Javadoc options':
    1. '-taglet net.sf.jsequnit.javadoc.SequenceTaglet'
    2. '-tagletpath path/to/the/jsequnit-<version>.jar';path/to/compiled/classes;path/to/compiled/test/classes;lib/junit-4.10.jar;lib/jseq-0.6.jar;lib/sdedit-light-3.1.jar'