how can remove fully qualified names for method parameters in @link/@see
I wrote a class which graphs items in which I have many @link tags in the javadocs.
A lot of the fields of this class, as part of their contract, declare that subclasses may override the field's value but that they must do so before a method named determineDimensions is called. Here is just one example:
/**
* The margin between all sides of the outer border and everything that is actually drawn inside (labels and graph).
*
* A subclass may assign a different value to this field, but it <i>must</i> do so before {@link #determineDimensions}
* is ever called (e.g. the subclass should reassign this inside its constructor).
*
* Contract: is not NaN or infinite and is >= 0.
*
* @serial
*/
protecteddouble marginBorder = 10;
That determineDimensions method, by the way, is declared as follows:
protectedvoid determineDimensions(Graphics2D g2)throws IllegalArgumentException, IllegalStateException{
My problem is that the html that is generated for, say, the above marginBorder field looks like this:
The margin between all sides of the outer border and everything that is actually drawn inside (labels and graph).
A subclass may assign a different value tothis field, but it mustdo so before determineDimensions(java.awt.Graphics2D) is ever called (e.g. the subclass should reassignthis inside its constructor).
Contract: is not NaN or infinite and is >= 0.
Notice how the parameter to determineDimensions is fully qualified (java.awt.Graphics2D instead of just Graphics2D). This is very annoying! I wish that it would simply print Graphics2D!
By the way, if I click on the link for determineDimensions(java.awt.Graphics2D) in the marginBorder field's javadocs and so come to the javadocs for the determineDimensions method itself, then I see that it looks like:
protectedvoid determineDimensions(Graphics2D g2)
throws IllegalArgumentException,
IllegalStateException
In other words, here the parameter is NOT fully qualified and in fact you can click on Graphics2D and goto sun's javadocs on it. This is how it should be, since I ran javadoc with the option -link http://java.sun.com/j2se/1.5.0/docs/api/.
So how can I get the @link to generate html that does not fully qualify parameters?
Notes:
1) there is only one version of my determineDimensions method, so there is no ambiguity in reference here
2) I tried running javadoc with the -noqualifier all option and that, surprisingly, did absolutely nothing
3) I searched on these fourms and could not find any relevant previous discussion; these ones were only loosely related:
http://forum.java.sun.com/thread.jspa?forumID=41&threadID=309852
http://forum.java.sun.com/thread.jspa?forumID=41&threadID=199555
I would love any feedback that you guys could offer.
Doug Kramer, you have any suggestions?
[3420 byte] By [
bbatmana] at [2007-10-2 9:29:29]
I'm surprised "-noqualifier all" didn't work. Sounds like a bug, which I
recommend you submit in a bug report. In case you haven't tried, please try:
-noqualifier java.awt
Perhaps it's not working because you've dropped the argument to
determineDimensions. We used to document you could do this, but
dropped the documentation because we couldn't guarantee it would
always work (even if there is technically no ambiguity). So you might try:
{@link #determineDimensions(Graphics2D)}
You probably are already aware that the brute force way to fix it is:
{@link #determineDimensions determineDimensions(Graphics2D)}
This relies on using the label parameter in {@link #member label}:
http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@link}
I know it's not satisfactory to add explicit labels and clutter up the source.
>I'm surprised "-noqualifier all" didn't work.
So was I.
>Sounds like a bug, which I recommend you submit in a bug report.
I will; see below for a full example which proves this is a bug
>In case you haven't tried, please try:
>-noqualifier java.awt
That fails too; see below.
>Perhaps it's not working because you've dropped the argument to
>determineDimensions. We used to document you could do this, but
>dropped the documentation because we couldn't guarantee it would
>always work (even if there is technically no ambiguity). So you might try:
>{@link #determineDimensions(Graphics2D)}
Great suggestion: the above does work.
But it is a major pain for my particular classes to go back and add the type of the args to all the method references in ~1,500 @links in my source code!
Doug, since you used to work at Sun on the javadoc team, do you have any idea what kind of priority sun places on bugs like this? Will it ever get solved? Maybe in 1.6? Or never?
>You probably are already aware that the brute force way to fix it is:
>{@link #determineDimensions determineDimensions(Graphics2D)}
>This relies on using the label parameter in {@link #member label}:
>http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@link}
>I know it's not satisfactory to add explicit labels and clutter up the source.
I should have mentioned that I was aware of that solution, but as you already know it is an even worse solution than adding param types as suggested above.
OK, as promised above, here is a worked example proving this as a bug. Consider this source file:
//package ...;
import java.awt.Graphics2D;
/**
* This class defines just a single method: {@link #arbitraryMethod}.
* @see #arbitraryMethod
*/
public class JavadocBug {
public static void arbitraryMethod(Graphics2D g2) {}
}
Obviously, place it in a file named JavadocBug.java and compile it via
javac JavadocBug.java
Then execute the bat file below, uncommenting whatever setting you want for the noqualifier env var, and see that it makes no difference because the @link and @see javadocs tags for the class always result in a link with the text
arbitraryMethod(java.awt.Graphics2D)
instead of the desired
arbitraryMethod(Graphics2D)
::--
:: MSDOS Bat file which makes javadocs for all the classes in this project.
::
:: The actions performed are:
:: 1) define some environmental variables used in this bat file
:: 2) generate javadocs for all these packages (i.e the ones listed in javaPackages.txt); execution will terminate if an error is detected
::
:: The current version of this file works under the JDK 1.5.0 javadoc tool,
:: altho it should only take a few minor tweaks (modify/remove a few options)
:: to get it work with older javadoc versions.
::
:: Side effect: echo will be off when this bat file finishes.
::--
::
::
@echo off
::-step 1): define environment variables
set javadocDir=.\javadoc
set jdkVersion=-source 1.5
set links=%links% -link http://java.sun.com/j2se/1.5.0/docs/api/
set noqualifier=
::set noqualifier=-noqualifier all
::set noqualifier=-noqualifier java.awt
set outputLevel=-verbose
set private=-private
set prompt=%promptNone%
::-step 2): generate javadocs
echo.
echo on
::
::
javadoc -breakiterator -classpath .\ -d %javadocDir% %jdkVersion% %links% %noqualifier% %outputLevel% %private% -serialwarn -sourcepath .\ -use JavadocBug.java
@if errorlevel 1 goto handleError
::
@echo off
::-error handling and final actions:
:handleError
@echo off
if not errorlevel 1 goto finalActions
echo.
echo ERROR DETECTED: jd.bat will TERMINATE PREMATURELY
:finalActions
@echo off
set prompt=%promptOriginal%
> Doug, since you used to work at Sun on the javadoc team, do you have any
> idea what kind of priority sun places on bugs like this? Will it ever get
> solved? Maybe in 1.6? Or never?
First, if the package names are properly omitted when the method names contain parameters but not when the parameter list is missing, then you can submit the bug, justifying it by this statement in the doc:
"If any method or constructor is entered as a name with no parentheses, such as getValue, and if there is no field with the same name, the Javadoc tool will correctly create a link to it, but will print a warning message reminding you to add the parentheses and arguments. If this method is overloaded, the Javadoc tool will link to the first method its search encounters, which is unspecified."
http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#typicalformsfor@see
It won't get fixed in 1.6, because that code is already frozen.
It's possible in 1.7, though in my estimate somewhat unlikely, because
this might not be considered a high enough priority bug, given the
scant resources that the javadoc tool is getting.
I'm sorry to say that Sun isn't doing much with javadoc. We worked hard to get a doclet programer hired for a couple of months to fix bugs for 1.6, and his work is done.
-Doug
BTW, you should formally submit your bug to Sun if you haven't already.
Doug,
I just submitted a bug report to Sun on this. Their auto email reply stated:
Your report has been assigned an internal review ID of: 624094
This review ID is NOT visible on on Sun Developer Network (SDN).
>It won't get fixed in 1.6, because that code is already frozen.
Nuts!
>It's possible in 1.7, though in my estimate somewhat unlikely, because
>this might not be considered a high enough priority bug, given the
>scant resources that the javadoc tool is getting.
>I'm sorry to say that Sun isn't doing much with javadoc. We worked hard to >get a doclet programer hired for a couple of months to fix bugs for 1.6, and >his work is done.
I have not tested this bug in 1.6 since I generally avoid beta software for my projects.
If anyone has downloaded the 1.6 betas, I would love to hear what happens when you run my code samples supplied above. Is the bug still present there? Because maybe in fixing other bugs, this one got fixed too.
If it is still present, then I am available for short term consulting work on issues like this. I live in New York City, about a 15 minute walk away from Sun's offices on Park Ave. I have other projects that I mainly want to work on, but would love to take a week or month off and work on fixing bugs that have annoyed me. Do you still know people at Sun so that you could put in a plug for me?
By the way, speaking of 1.6, does anyone know the expected production worthy release of it?
In case anyone is interested, Sun just got back to me and is classifying it as a bug. Their response:
We have determined that this report is a new bug and entered the bug into our internal bug tracking system under Bug Id: 6372068.
You can monitor this bug on the Java Bug Database at
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6372068.
