Want to be able to specify a root package on the command line and
have javadoc traverse and generate docs for all subpackages.  
Would also need to be able to exclude packages and/or classes
you want to skip over.

Also known as "recursive descent" (or "recursively descend").



Subject: RE: Javadoc - Recursive package search
Date: Fri, 22 Aug 1997 09:24:05 +0100

I think I've probably got my wires crossed!  What I was trying to say
was that if you have a directory tree as follows:

Halifax
    |----General
	  |------HxDate
          |   	  |-------HxData.java
          |
	  |------HxInt
          |   	  |--------HxInt.java
          |
	  |------HxString
          |   	  |-------HxString.java	  
          |
	  |-------HxGeneral.java
          |
	  |-------HxFile.java

In which all files/classes belong to the package Halifax.General you
would expect the following command to pick up all of the source files
even the ones in the sub directories:

Javadoc Halifax.General

or at least.

Javadoc Halifax.General.*

Unfortunately it doesn't happen.

For those who need this feature because they have hit the 
command line-length limit (1000 characters on Windows),
we have already implemented a different solution for that --
the @file argument which points to a file that can contain the
rest of the arguments.  This works in 1.2 Beta4.  For more 
information, see:
http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/javadoc.html#argumentfile
  xxxxx@xxxxx   1998-10-06

Can someone write a wrapper in Java to perform this function?
  xxxxx@xxxxx   1998-04-03

There is a huge demand from the JDC for this functionality and it 
should be added to the tool itself.  For backward compatibility
this functionality will require a flag and a flag or flags will
be needed to exclude packages.
  xxxxx@xxxxx   1998-10-06

Raised priority from 5 to 4 and added workaround.
  xxxxx@xxxxx   1998-10-06

Add option -recurse so that the default is to not recurse, for backward
compatibility.  However, if we require package names, then you
could not run javadoc on all the java.* packages:  javadoc -recurse java
since "java" is not a package.

Or should -exclude take a package or class name, so you could
combine it with -recurse:   javadoc -recurse package1 -exclude package2
This should work at the member level, class level or package level.
  xxxxx@xxxxx   1998-12-15

Further design and discussion needed - fix in 1.3.
  xxxxx@xxxxx   1999-02-04

Because this is so highly requested, how about if we write a wrapper to do
this for Merlin (1.4), then add it to Javadoc later.
  xxxxx@xxxxx   2000-12-06

This RFE has been implemented.  Location of implemetation:

src/share/javac/com/sun/tools/javadoc/JavadocTool.java
src/share/javac/com/sun/tools/javadoc/Start.java
src/share/javac/com/sun/tools/javadoc/resources/javadoc.properties

  xxxxx@xxxxx   2001-07-20

The current behavior is inconvenient. But for know
you can work-around this by specifying each package
on the command line.
i.e. javadoc -d <docdir> Halifax Halifax.General Halifax.General.HxDate
...
 

I'd rather see this as an optional flag.  Current implementation allows you to
have sub-packages which are not exposed to your customer which I like.  I'd
like to have a -r flag to process recursively or something.

This is especially annoying under crappy operating systems like
WinNT which limit the length of a command line to about 256 characters.
Not very useful when you are generating javadoc for a long list of
packages with a command whose length exceeds this limit.

As for excluding sub-packages, I like the way PolarDoc implements this; it
defaults to including all subdirs, and you may use the -x mypackage switch to
exclude packages you don't want javadoc'd.
Well, for that matter, JavaSoft could learn quite a bit from PolarDoc!

This code will generate the javadoc for large packages which extend beyond the
256 character maximums on win32 systems:
It also redirects the output to a file for perusal since the command line
prompt is not scrollable on win32 systems.
Just include your options in the array as below:
import sun.tools.javadoc.*;
import java.io.*;
public class generateDocs
{
	public static final String myPackages[] = {
		"-version",
		"-author",
		"-private",
		"mypackage",
		"mypackage.subpackage",
		"mypackage.subpackage2",
		"mypackage2.subpackage",
		"mypackage2.subpackage2"
};

	public static void main(String[] args)
	{
		for(int i = 0; i < 10; i++)
		{
			generateDocs.doYourStuff();
		}
	}
	public static void doYourStuff()
	{
		try
		{
			File outFile = new File("c:\\logs\\javadoc.log");
			PrintStream outStream = new PrintStream(new FileOutputStream(outFile));
			System.setOut(outStream);
			System.out.println("Beginning documentation creation");
			sun.tools.javadoc.Main.main(myPackages);
		}
		catch(IOException e)
		{
			System.out.println("Error setting stderr");
			e.printStackTrace();
		}
	}

I agree with this bug : my application has
186 packages !!! Javadoc is hell for me !!
Another bug : under WinNT the option -J<flag>
doesn't work. With my 911 classes, I must run
"java -mx32m -ms32m sun.tools.javadoc.Main ...".

Please do this with a -recursive option to change 
from the normal functionality.

Hi,
I don't know why this option was never added in the first place.
Seems like just having an option (like "dir /s"in DOS) would have
been common sense.
If you don't want it, don't slash it. 
It would be a REAL time saver.

A recursive flag would greatly simplify javadoc generation for my deeply
packaged classes.

It would be interesting to be able to specify
either both recursive and non recursive packages
in one command line. Maybe using the syntax:
javadoc <options> package1.* package2 package3.*.*
package1 would include all first level subpackage, and
package2 would include no other subpackage, and
package3 would include all second level subpackages (recurse twice).
This is simple, and like "-r" is similar to command
line shells (replacing "/" with ".", eg. "ls
bin/*/*").
But, this is *much* more powerful.

The problem with this feature request is figuring
out how to "prune" unwanted packages from the
list.  Personally, I use a "ksh" script to generate
a list of package names similar to the following:

***** BEGIN get_javadocdirs SCRIPT *****
#!/ksh
#
# Name: get_javadocdirs
# Usage: get_javadocdirs <sourcepath>
#
# Get a list of the directories, pruning
# the CVS and test subdirectories
cd $1
ALL_PKGDIRS=`find . -name CVS -prune -o -name test -prune -o -type d -print
# Prune any directories that don't contain a java 
# file
PKGDIRS=""
for DIR in $ALL_PKGDIRS; do
  LSDIR=`ls $DIR/*.java 2> /dev/null`
  if [ ! -z "$LSDIR" ]; then
    PKGDIRS=`echo $PKGDIRS $DIR`
  fi
done
# Convert directory names to package names
#
PKGNAMES=""
for DIR in $PKGDIRS; do
  PKGNAME=`echo $DIR | sed -e 's/\.\///g'`
  PKGNAME=`echo $PKGNAME | sed -e 's/\//\./g'`
  PKGNAMES=`echo $PKGNAMES $PKGNAME`
done
# Return the list of package names
#
echo $PKGNAMES
***** END get_javadocdirs SCRIPT *****
Similar scripts could be written in perl
or the scripting language of your choice.  As I 
said, perhaps the biggest problem is deciding 
how to prune directories from your list of
package names.
Using this script, javadoc generation is simply:
javadoc -d <destdir> `get_javadocdirs <basepath>`
Of course, this is primarily a Unix solution. 
However, it will work on Win32 using a Unix toolkit
like the GnuWin32 tools.  As for other platforms
(e.g. Mac), I'm not sure what the solution would be.

Another possible solution is to allow javadoc to read an ascii file containing
the list of package names.  I.e.:
javadoc -d [dest] -f [filename] ...
The input file could be created on Wintel machines using a command like: 
"dir /s /aD /b /v * >[filename]" 
Then an editor can be used to remove the unwanted packages.

Here is an easy work-around on Windows NT using 1.2 beta4 or later:
1.  Type the following on the command line from
    the root of you packages to get a file
    containing a listing of directories:
       dir /ad /s /b > packages.txt
2.  Then use @packages.txt for your source.
       e.g. javadoc @packages.txt
This could be done in one step if javadoc accepted stdin for the files so that
it would have the ability to accept piped input.  
       e.g.  dir /ad /s /b | javadoc

It's really painful to not have this -r option !!
Dot it before jdk1.2 last release !!
it's not a hard feature to implement !! Lazy ??

Oops, I meant the slashes would have to be changed
to dots.

The use of "packages.text" mentioned by James Schreiver, 
should work fine.  However, his mention of:
dir /ad /s /b | javadoc
would not work as-is (even if Javadoc accepted stdin)
because Javadoc takes package names not directory 
names -- the dots would have to be changed to 
slashes somehow.
-Doug Kramer
 Javadoc team

Polardoc kicks Javadoc's ass

Workaround:
On a Windows box, make a batch file in
your source dir like:
dir /a-d /b /s *.java > ~files
javadoc -d ..\doc @~files
del ~files
You might modify this to take a source dir as a parameter.
This simply generates a file listing to be fed into javadoc.
In any case, if this is done you still won't get any package
documentation as described in:
4214962
Synopsis
No package info generated for source files passed on command line

Surely the way to handle pulling the directories to parse on
the command line is to have the "filename" - be mapped to
reading from System.in (many Unix tools do just this) so the
following command line would do the trick...
   dir /ad /s /b | javadoc @-
Well, except for the required filter (producing the following
Solaris command line...)
   find hierRoot -type d -print | sed s,/,.,g | javadoc @-
As it is, at the moment I have a *really* crufty shell-script to
handle all this for me which also requires manual maintenance.
Anything that lets me get away from that is deeply welcome!

Should be obvious

This would be very convenient - Right now I have to 
maintain a separate batch program with all the package 
names.  I agree it should be a -r (or -s) option.  In order 
to implement this, I think the java.lang.Package class 
might need a method like: public Package[] 
Package.getSubpackages(), or some other way to traverse the 
package tree via reflection.

I do like the way Javadoc handles a list of packages, through the use of @package-list parameter. Many of 
my packages have a "test" subpackage, which should not pollute my documentation.
My personal opinion is that a package name should support the asterisk wildcard ('*'), in order to say that 
subpackages should be added.

Ant, a tool for automating build processes, has a "javadoc" 
command that does the job nicely. I often create an ant-
build.xml for projects just for generating javadocs.

Here's the URL:
http://jakarta.apache.org/ant/

I also use Jakarta Ant to build my javadoc.  I reckomend it 
to everyone.

Under Windows 2000 (and possibly NT) you can use:

dir /b /s *.java > files.txt

to generate a list of files in a directory.