Products         News         Downloads         Licensing         Shop         Support    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
Integrations
Bundles
 DocFlex/Javadoc
Overview
Documentation
Installation & Config Files
DocFlex Doclet
Integrations
FAQ
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Use
Licensing
Shop
Support
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

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"/>
<!-- 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="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 &amp; Maven Integration Demo"
<!-- The output format -->
-format HTML
<!-- Suppress 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, 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 &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
<!-- 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:

Running DocFlex 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 DocFlex Doclet main class: com.docflex.javadoc.Doclet
  4. 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.
  5. Now, you can click “Next”.
Then, you will see the second dialog:
Running DocFlex 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).

    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!

  2. 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!

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.