JDK-4113483 : javadoc tool: Implement a public way to invoke javadoc from within java
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.2.0
  • Priority: P4
  • Status: Closed
  • Resolution: Fixed
  • OS: generic,windows_nt
  • CPU: generic,x86
  • Submitted: 1998-02-19
  • Updated: 2014-05-05
  • Resolved: 2000-03-10
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availabitlity Release.

To download the current JDK release, click here.
Other
1.4.0 betaFixed
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