United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4113483 : javadoc tool: Implement a public way to invoke javadoc from within java

Details
Type:
Enhancement
Submit Date:
1998-02-19
Status:
Closed
Updated Date:
2014-05-05
Project Name:
JDK
Resolved Date:
2000-03-10
Component:
tools
OS:
windows_nt,generic
Sub-Component:
javadoc(tool)
CPU:
x86,generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.2.0
Fixed Versions:
1.4.0 (beta)

Related Reports

Sub Tasks

Description
Name: rm29839			Date: 02/19/98

The doclet API makes possible a new class of
tools and it would be easier and cleaner if there
was a published way of invoking the javadoc program
from within a java program (without having to exec
it, yuck.) I'm guessing, based on looking at the
120b2 classes.zip that it's probably just a 
question of invoking

 sun.tools.javadoc.Main.main(...)

But if you guys published that as one line of the
doclet API documentation it would make using it
complete righteous as opposed to slightly kludgy.
(Review ID: 25090)
======================================================================

See public summary for full description of problem and resolution.
robert.field@Eng 2000-03-01

                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
generic
merlin-beta

FIXED IN:
merlin-beta

INTEGRATED IN:
merlin-beta

VERIFIED IN:
merlin-rc1


                                     
2004-06-14
PUBLIC COMMENTS

Add a programmatic interface to the javadoc tool.  Interface
is in com.sun.tools.javadoc.Main - details below.
However, once there is a programmatic interface, that interface
can be called multiple times in one run - as a result the
javadoc tool and the standard doclet must be made re-entrant.

--------------

public static void main(java.lang.String[] args)

      Command line interface.
      Parameters:
            args - The command line parameters.


public static int execute(java.lang.String[] args)

      Programmatic interface.
      Parameters:
            args - The command line parameters.
      Returns:
            The return code.

public static int execute(java.lang.String programName,
                          java.lang.String[] args)

      Programmatic interface.
      Parameters:
            programName - Name of the program (for error messages).
            args - The command line parameters.
      Returns:
            The return code.


public static int execute(java.lang.String programName,
                          java.lang.String defaultDocletClassName,
                          java.lang.String[] args)

      Programmatic interface.
      Parameters:
            programName - Name of the program (for error messages).
            defaultDocletClassName - Fully qualified class name.
            args - The command line parameters.
      Returns:
            The return code.


public static int execute(java.lang.String programName,
                          java.io.PrintWriter errWriter,
                          java.io.PrintWriter warnWriter,
                          java.io.PrintWriter noticeWriter,
                          java.lang.String defaultDocletClassName,
                          java.lang.String[] args)

      Programmatic interface.
      Parameters:
            programName - Name of the program (for error messages).
            errWriter - PrintWriter to receive error messages.
            warnWriter - PrintWriter to receive error messages.
            noticeWriter - PrintWriter to receive error messages.
            defaultDocletClassName - Fully qualified class name.
            args - The command line parameters.
      Returns:
            The return code.
                                     
2004-06-10
EVALUATION

You are correct, both that that is the entry point and that it is kludgy.
Note: it shouldn't be in sun.*

Mark Anderson (###@###.###, who we met at JavaOne) points out 
that the mentioned entry point is actually not accessible, since the 
class is package private and final.  He would like this available for FCS.  
Robert's response:  "The class would have to be public. We can consider 
making it so."
I have changed this bug's priority from 5 to 4.
doug.kramer@Eng 1998-06-15

Mark Anderson's further clarification:
    Thanks for the reply and thanks for considering this!  
Don't feel like you have to make Main.main() public
if you would rather wrapper this access with a less "kludgey" public static
interface that would, in turn, call Main.main().  As long as there is
something to call where I can specify the list of classes/packages to
process and the name of my doclet code.  Even passing in a string
similar to the argument list when running javadoc from the command
line would be fine.
    My primary goal is to be able to use doclet technology "inside" a
Java application (i.e., at various times, I could invoke javadoc via
some class interface to parse some java files and call my specified
doclet class so I can get Root and its associated objects to use in
my program).  Right now to do this, I have to essentially build my
"application" inside my doclet and let the javadoc utility drive the show.
    So far, I am only experimenting with this approach on a small scale,
but this type of flexibility with using javadoc and doclets opens up
some interesting ideas.
doug.kramer@Eng 1998-06-16

Another comment from Mark Anderson:
    I learned one more thing while experimenting with doclets today.
When you return from the start(Root) method in a doclet, javadoc
must be calling System.exit(0) soon after that (normal behavior for
a command line utility).  I found this out when the UI window I
created in my start(Root) method never showed up after I returned
from start(Root).  I have since worked around this be delaying my
return from start(Root) until I close the UI.
    So, how does this relate to our earlier discussion about providing
a way to invoke javadoc (Main.main() or equivalent) from other Java
code?  Well, if this is provided, javadoc should NOT call System.exit(0)
when the doclet returns because in this scenario, javadoc is not the
application.  The Java code that invoked it is.  It would be rather rude
for javadoc to kill the application in this scenario. :-)
doug.kramer@Eng 1998-06-16

I am re-opening this RFE.  According to Robert:
   I don't know why this was closed, it wasn't fixed.  And should be.
doug.kramer@Eng 2000-01-19

See public summary for resolution.
robert.field@Eng 2000-03-01
                                     
2000-01-19



Hardware and Software, Engineered to Work Together