Making Javadoc work with Ant (or without it)
I need to add Java doc to my Ant build file, with the following requirements:
- All java files under the "WEB-INF\src" directory must be documented. They belong to many different packages and reside in many different folders.
- The library JAR files should not be documented. There is just too many and it would take forever. These files reside under "WEB-INF/lib". (NOTE: A lot of the *.java files use these libraries, but I don't want their documentation).
- The output HTML should be placed under "WEB-INF\docs" directory.
If somebody knows how to do it with Ant, that would be great. But command-line javadoc will do also.
NOTE: I will be running both from the parent directory of WEB-INF.
I'm not an expert on Ant, but here's the javadoc command.
You didn't say which version of Javadoc you want to use, but if
you're using the latest, the simplest way to do it
is with the -subpackages option:
javadoc -d WEB-INF\docs -classpath WEB-INF/lib -sourcepath WEB-INF\src
-subpackages com1:com2
where com1:com2 are the top-level subpackages that you want javadoc
to recurse down from.
Do not use 1.4.0, as it has a bug that will mistakenly document the
-classpath classes. Use 1.4.1 instead. (Perhaps you meant a backslash
in WEB-INF\lib.)
There are many options you can add, such as
-J-Xmx100M to increase the amount of memory,
-exclude to exclude any packages from recursion,
-use to show the cross-reference of class and package uses,
-overview to include a page that describes the set of packages,
-doctitle to assign a titel to the document,
-windowtitle to assign a title to the window,
-splitIndex to split the index to one web page per letter,
-header to add a running header,
-bottom to add a fottnote to all pages such as for copyright, and
-group to gropu packages on the overview page.
-overview \java\jdk\src\share\classes\overview.html^
-use^
-splitIndex ^
-windowtitle 'Java 2 Platform v1.2 API Specification'^
-doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform v1.2 API Specification' ^
-header '<b>Java 2 Platform </b>
<font size="-1">v1.2</font>' ^
-bottom '<font size="-1">Java is a trademark or registered trademark of Sun Microsystems,
Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc.
901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' ^
-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" ^
-group "Extension Packages" "javax.*"^
-J-Xmx180m^
-Doug Kramer
Javadoc team
LoneDeranger, although I am a bit rusty since it was a while ago, something like this should work.
<javadoc destdir="WEB-INF/docs"
classpath="WEB-INF/lib/myJar1.jar;WEB-INF/lib/myJar2.jar">
<packageset dir="WEB-INF/src" defaultexcludes="yes">
<include name="com/mycompany/mypackage/**" />
<exclude name="com/mycompany/mypackage/unwantedpackage/**"/>
</packageset>
</javadoc>
Now from this you can include and exclude more packages as you see fit. If you want to include everything, just remove the exclude line and use the wildcard in the include where you need it.
Apart from this you may want to add more parameters (document headers for example), they are all available from Ants page for the Javadoc task at http://jakarta.apache.org/ant/manual/CoreTasks/javadoc.html.
