 DocFlex/Javadoc - Documentation - Integrations
Apache Ant
You can easily integrate DocFlex 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 'java5' contained in 'demo' directory
of DocFlex/Javadoc
installation at C:\docflex-javadoc.
Here is a simple Windows command file that launches such a generation:
set DFH=C:\docflex-javadoc |
javadoc |
-J-Xmx512m
-sourcepath %DFH%\demo
-d %DFH%\out
-docletpath %DFH%\lib\docflex-javadoc.jar
-doclet com.docflex.javadoc.Doclet
-template %DFH%\templates\javadoc\FramedDoc.tpl
-p:windowTitle "DocFlex/Doclet Demo"
-p:docTitle "DocFlex Ant Demo"
-p:include.tag.custom "todo:a:To Do:"
-p:include.tag.custom "prj\:type:opt:Project Type:"
-format HTML
-nodialog
-launchviewer=false
java5
|
The following is an equivalent Ant build.xml file doing the same:
build.xml
|
<?xml version="1.0"?>
<project basedir="." name="DocFlex Ant Demo">
<!-- the location of DocFlex/Javadoc home directory -->
<property name="DFH" value="C:/docflex-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="${DFH}/demo" destdir="${DFH}/out">
<!-- specifying the doclet -->
<doclet name="com.docflex.javadoc.Doclet" path="${DFH}/lib/docflex-javadoc.jar">
<!-- specifying the doclet command-line parameters -->
<!-- the main template -->
<param name="-template" value="${DFH}/templates/JavadocPro/FramedDoc.tpl"/>
<!-- template parameters -->
<param name="-p:windowTitle" value="DocFlex/Doclet Demo"/>
<param name="-p:docTitle" value="DocFlex 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"/>
<!-- supress 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="java5.*"/>
</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:\jdk1.6
call %ANT_HOME%\bin\ant.bat demo
(Note, the BAT should be started from the directory containing the build.xml file!)
Apache Maven
Integrating DocFlex Doclet
with the Apache Maven
automated build system may be more complicated.
The support of custom doclets (in general) by the
Maven Javadoc Plugin
seems to be rather erratic.
So, it may take some efforts to get the DocFlex Doclet
work with a particular Maven version.
Here is what we have found.
Maven 2.0.x
In this version, the <docletPath> element, which is provided by the
Maven Javadoc Plugin
to specify the file pathname of the custom doclet, actually doesn't work.
Instead, you need to install the docflex-javadoc.jar (or docflex-doclet.jar
in DocFlex/Doclet edition)
into the Maven repository. But you cannot do it directly!
Anything stored in the Maven repository is associated with a certain artifact.
Each artifact is identified by three things: { groupId, artifactId, version }.
Those properties need to be specified anywhere you want to use a feature associated with that
artifact. (Maven itself avoids working with direct file locations!)
With DocFlex Doclet, we shall associate
the following artifact identifiers (the version will be the last DocFlex/Javadoc version number):
| groupId |
= |
docflex |
| artifactId |
= |
docflex-doclet |
| version |
= |
1.6.0 |
Then, to install DocFlex Doclet
in the Maven repository you can use the following command:
mvn |
install:install-file
-Dfile=C:\docflex-javadoc\lib\docflex-javadoc.jar
-DgroupId=docflex
-DartifactId=docflex-doclet
-Dversion=1.6.0 -Dpackaging=jar
|
Now, you can configure the
Maven Javadoc Plugin
in your project POM file like the following:
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 DocFlex Doclet -->
<doclet>com.docflex.javadoc.Doclet</doclet>
<docletArtifact>
<groupId>docflex</groupId>
<artifactId>docflex-doclet</artifactId>
<version>1.6.0</version>
</docletArtifact>
<!-- Specifying command-line parameters for DocFlex Doclet -->
<additionalparam>
<!-- The main template -->
-template C:/docflex-javadoc/templates/JavadocPro/FramedDoc.tpl
<!-- Pass template parameters -->
-p:windowTitle "DocFlex Doclet Output"
-p:docTitle "DocFlex/Javadoc & Maven Integration Demo"
<!-- The output format -->
-format HTML
<!-- Supress showing up the doclet GUI -->
-nodialog
<!-- Do not launch documentation viewer -->
-launchviewer=false
<!-- Tell DocFlex Doclet the location of the output directory -->
-d ${project.build.directory}/site/docflex_doclet_output
</additionalparam>
<!-- Tell Maven the output directory name -->
<destDir>docflex_doclet_output</destDir>
<!-- For the project-reports page -->
<name>DocFlex Doclet Output</name>
<description>
A Java API documentation generated with DocFlex Doclet.
</description>
</configuration>
</plugin>
</plugins>
</reporting>
...
</project>
|
Maven 2.2.x / 3.0.x
In these Maven versions, the <docletPath> element, which specifies
the custom doclet class pathname, does work!
So, installing DocFlex Doclet as an “artifact”
in the Maven repository is not necessary any longer and the project POM file becomes a bit simpler.
|
Yet, the new versions of
Maven Javadoc Plugin
are not without oddities too.
For instance, now Maven always emits some Standard Doclet options even in the case of custom doclet,
as well as a -link option,
which in its argument provides no URL but a local file pathname.
So, more special efforts were needed to work around all this!
See also the note to Setting template parameters via Standard Doclet options for that matter.
|
Here is a sample project POM file that did work (tested with Maven 2.2.1 and Maven 3.0.4):
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 DocFlex Doclet -->
<doclet>com.docflex.javadoc.Doclet</doclet>
<docletPath>C:/docflex-javadoc/lib/docflex-javadoc.jar</docletPath>
<!-- Specifying command-line parameters for DocFlex Doclet -->
<additionalparam>
<!-- The main template -->
-template C:/docflex-javadoc/templates/JavadocPro/FramedDoc.tpl
<!-- Pass template parameters -->
-p:windowTitle "DocFlex Doclet Output"
-p:docTitle "DocFlex/Javadoc & 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
<!-- Supress showing up the doclet GUI -->
-nodialog
<!-- Do not launch documentation viewer -->
-launchviewer=false
<!-- Tell DocFlex Doclet the location of the output directory -->
-d ${project.build.directory}/site/docflex_doclet_output
</additionalparam>
<!-- Tell Maven the output directory name -->
<destDir>docflex_doclet_output</destDir>
<!-- For the project-reports page -->
<name>DocFlex Doclet Output</name>
<description>
A Java API documentation generated with DocFlex Doclet.
</description>
</configuration>
</plugin>
</plugins>
</reporting>
...
</project>
|
The complete working example is included in both
DocFlex/Javadoc
and
DocFlex/Doclet
archives prepared for downloads.
Eclipse
Using DocFlex 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:
Make sure the following settings are specified:
-
In the “Javadoc command” field, provide the location of the Javadoc executable
in some JDK installed on your system.
-
Select “Use Custom Doclet”.
-
In the “Doclet name” field, specify the name of the
DocFlex Doclet main class:
com.docflex.javadoc.Doclet
-
In the “Doclet class path” field, specify the full pathname of the DocFlex Doclet
Java library file:
docflex-javadoc.jar or docflex-doclet.jar
(depending on the edition).
This file is located in the 'lib' directory of your
DocFlex/Javadoc
(or DocFlex/Doclet)
installation.
-
Now, you can click “Next”.
Then, you will see the second dialog:
In this dialog, check the following fields:
-
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).
Note: If you leave this field empty, Javadoc
(that is the DocFlex Doclet)
may slow down very much, especially on a big project, and you may get eventually
java.lang.OutOfMemoryError exception!
-
The “Extra Javadoc options” field is for the doclet-specific options.
All the command-line options processed by DocFlex 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 DocFlex 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 DocFlex 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 DocFlex 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),
DocFlex Doclet
can be integrated with probably anything that runs Javadoc itself.
To use DocFlex Doclet with a particular system,
basically, you need to know how to specify the following settings:
- The doclet class name
- The doclet class path
- The doclet-specific Javadoc options
-
The maximum heap size used by the JVM that runs Javadoc
(i.e. how to pass to it the -Xmx option).
Once you know those things, you will be able to run
DocFlex Doclet within your tool!
|
