United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4074234 : javadoc tool: Traverse/recurse all subpackages with "javadoc "

Details
Type:
Enhancement
Submit Date:
1997-08-25
Status:
Closed
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2001-08-07
Component:
tools
OS:
solaris_2.5,solaris_2.5.1,generic
Sub-Component:
javadoc(tool)
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.0.2,1.1,1.2.0
Fixed Versions:
1.4.0 (beta2)

Related Reports
Duplicate:
Duplicate:

Sub Tasks

Description
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").

From: "Blackett, Darren (IS - XCEL & Application Infrastructure)" <###@###.###>
To: "'###@###.###'" <Doug.Kramer@Eng>
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.

                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
merlin-beta2

FIXED IN:
merlin-beta2

INTEGRATED IN:
merlin-beta2

VERIFIED IN:
merlin-beta2


                                     
2004-06-14
PUBLIC COMMENTS

This RFE has been implemented.  I have added two command-line flags to javadoc:
 -subpackages <packagename>
        Which causes javadoc to include the named package and all subpackages; and
-exclude <packagename>
        Which causes javadoc to unconditionally exclude the named package
        from the list of packages to document even if it would otherwise
        be included by some previous or later -subpackages command-line
        flag. For example
                -exclude java.lang.ref -subpackages java
        Would include java.io, java.util, java.lang, etc, but not java.lang.ref.

jamie.ho@Eng 2001-07-20
                                     
2001-07-20
EVALUATION

Can someone write a wrapper in Java to perform this function?
doug.kramer@Eng 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.
robert.field@Eng 1998-10-06

Raised priority from 5 to 4 and added workaround.
doug.kramer@Eng 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.
doug.kramer@Eng 1998-12-15

Further design and discussion needed - fix in 1.3.
robert.field@Eng 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.
doug.kramer@Eng 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

jamie.ho@Eng 2001-07-20
                                     
2001-07-20
WORK AROUND

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
doug.kramer@Eng 1998-10-06
                                     
1998-10-06



Hardware and Software, Engineered to Work Together