FlexDoc/Javadoc - Integrations

Apache Ant

You can easily integrate FlexDoc Doclet with the Apache Ant automated build system.

Here is an example.

Let's suppose, we want to generate a framed HTML documentation using FramedDoc.tpl template by the Java source package 'java8' contained in the directory:

C:\flexdoc-javadoc\demo\
Here is a simple Windows command file that launches such a generation:
set FDH=C:\flexdoc-javadoc
javadoc  -J-Xmx512m -sourcepath %FDH%\demo -d %FDH%\out -docletpath %FDH%\lib\flexdoc-javadoc.jar -doclet xyz.flexdoc.javadoc.Doclet -template %FDH%\templates\classic\FramedDoc.tpl -p:windowTitle "FlexDoc/Javadoc Demo" -p:docTitle "FlexDoc Ant Demo" -p:include.tag.custom "todo:a:To Do:" -p:include.tag.custom "prj\:type:opt:Project Type:" -format HTML -nodialog -launchviewer=false java8
The following is an equivalent Ant build.xml file that does the same:

build.xml

<?xml version="1.0"?>
<project basedir="." name="FlexDoc Ant Demo">
<!-- the location of FlexDoc/Javadoc home directory -->
<property name="FDH" value="C:/flexdoc-javadoc"/>
<target name="demo">
<!--
Specifying Javadoc task.
The 'maxmemory' attribute sets the maximum heap size
available to the Java VM running Javadoc.
-->
<javadoc maxmemory="512m" sourcepath="${FDH}/demo" destdir="${FDH}/out">
<!-- specifying the doclet -->
<doclet name="xyz.flexdoc.javadoc.Doclet" path="${FDH}/lib/flexdoc-javadoc.jar">
<!-- specifying the doclet command-line parameters -->
<!-- the main template -->
<param name="-template" value="${FDH}/templates/classic/FramedDoc.tpl"/>
<!-- template parameters -->
<param name="-p:windowTitle" value="FlexDoc/Javadoc Demo"/>
<param name="-p:docTitle" value="FlexDoc Ant Demo"/>
<param name="-p:include.tag.custom" value="todo:a:To Do:"/>
<param name="-p:include.tag.custom" value="prj\:type:opt:Project Type:"/>
<!-- the output format -->
<param name="-format" value="HTML"/>
<!-- suppress showing up the doclet GUI -->
<param name="-nodialog"/>
<!-- do not launch documentation viewer -->
<param name="-launchviewer=false"/>
</doclet>
<!-- specifying the Java source package to document -->
<package name="java8.*"/>
</javadoc>
</target>
</project>

To run that build.xml file, you can use a Windows BAT specified like the following:

set ANT_HOME=C:\apache-ant
set PATH=%ANT_HOME%\bin;%PATH%
set JAVA_HOME=C:\Program Files\Java\jdk1.8
call %ANT_HOME%\bin\ant.bat demo
(Note, the BAT should be started from the directory containing the build.xml file!)

Apache Maven

Integrating FlexDoc Doclet with the Apache Maven automated build system may be a bit more complicated because they tend to constantly change something. So, what worked some time ago, may be not working now.
For instance, when preparing the last FlexDoc/Javadoc release, we have discovered that the <additionalparam> element used in Maven POM file to pass custom doclet options doesn't work and seems to have been replaced with a new <additionalOptions> element that works the same.

However, that holds only for Maven working under MS Windows. Under macOS and Linux, the opposite is true: <additionalparam> does work, but <additionalOptions> is not recognized.

The following sample project POM file did work with Maven 3.6.0 on Windows:

pom.xml

<project>
...
<reporting>
<plugins>
<!-- Configure Maven Javadoc plugin -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<!-- The maximum heap size available to JVM when running Javadoc -->
<maxmemory>512m</maxmemory>
<!-- Using FlexDoc Doclet -->
<doclet>xyz.flexdoc.javadoc.Doclet</doclet>
<docletPath>C:/flexdoc-javadoc/lib/flexdoc-javadoc.jar</docletPath>
<!-- Specifying command-line parameters for FlexDoc Doclet -->
<additionalOptions>
<!-- The main template -->
-template C:/flexdoc-javadoc/templates/classic/FramedDoc.tpl
<!-- Pass template parameters -->
-p:windowTitle "FlexDoc Doclet Output"
-p:docTitle "FlexDoc/Javadoc &amp; Maven Integration Demo"
-p:include.tag.custom "todo:a:To Do:"
-p:include.tag.custom "prj\\:type:opt:Project Type:"
<!-- The output format -->
-format HTML
<!-- Suppress showing up the doclet GUI -->
-nodialog
<!-- Do not launch documentation viewer -->
-launchviewer=false
</additionalOptions>
<!-- Tell Maven the output directory name -->
<destDir>flexdoc_doclet_output</destDir>
<!-- For the project-reports page -->
<name>FlexDoc Doclet Output</name>
<description>
A Java API documentation generated with FlexDoc Doclet.
</description>
<!-- Specifying the Java source package to document -->
<subpackages>java8</subpackages>
</configuration>
</plugin>
</plugins>
</reporting>
...
</project>

The complete working example is included in FlexDoc/Javadoc archive prepared for downloads.

Eclipse

Using FlexDoc Doclet with Eclipse is most simple. You just need to fill out two dialogs.

First, select in the Eclipse main menu the «Project | Generate Javadoc...» item. The following dialog will show up:

Running FlexDoc Doclet from Eclipse

Make sure the following settings are specified:
  1. In the «Javadoc command» field, provide the location of the Javadoc executable in some JDK installed on your system.
  2. Select «Use Custom Doclet».
  3. In the «Doclet name» field, specify the name of the FlexDoc Doclet main class: xyz.flexdoc.javadoc.Doclet
  4. In the «Doclet class path» field, specify the full pathname of the FlexDoc Doclet Java library file: flexdoc-javadoc.jar. This file is located in the 'lib' directory of your FlexDoc/Javadoc installation.
  5. Now, you can click «Next».
Then, you will see the second dialog:

Running FlexDoc Doclet from Eclipse

In this dialog, check the following fields:
  1. In the «VM options» field, you should specify the maximum memory heap size available to the JVM that will run Javadoc (512Mb may be just enough).

    If you leave this field empty, Javadoc (that is the FlexDoc Doclet) may slow down very much, especially on a big project, and you may get eventually java.lang.OutOfMemoryError exception!

  2. The «Extra Javadoc options» field is for the doclet-specific options. All the command-line options processed by FlexDoc Doclet that you may ever need should be specified here!

    In particular, with the -d option you should specify the output directory for the generated documentation.

    Also, unless -nodialog option is specified directly, the FlexDoc Doclet will launch the Doclet GUI over Eclipse. (In fact, since Javadoc is run by a different JVM, the Doclet GUI will be completely independent on Eclipse).

    Remember also that all missing options that the FlexDoc Doclet may need (including template parameters) will be taken from the generator.config created when the Doclet GUI was invoked the last time. (So, you should not wonder, how FlexDoc Doclet knows some specific settings you did not provide to it.)

Now, you may click «Finish» button to start Javadoc.

Other Systems

As being a Javadoc Doclet (that is a special plug-in for Javadoc), FlexDoc Doclet can be integrated with probably anything that runs Javadoc itself.

To use FlexDoc Doclet with a particular system, basically, you need to know how to specify the following settings:

Once you know those things, you will be able to run FlexDoc Doclet within your tool!