@see System doesn't work
I can't seem to get Javadoc 1.3.1_02 to find java.lang.System with @see and @link.
I've tried:
@see System
@see java.lang.System
@see System#currentTimeMillis
@see java.lang.System#currentTimeMillis
Other classes from java.lang.* work, like:
@see Thread
@see Thread#interrupt
@see Thread#sleep
Here's my command line (from a build.bat file, including the JavadocRecurse to generate the package list):
java -classpath %classpath%;%jar% dynamic.tools.JavadocRecurse %TEMP%\%project%_packages.txt %sourceDir%
%jdk%\bin\javadoc ^
-classpath %classpath% ^
-author ^
-version ^
-use ^
-splitindex ^
-windowtitle "iFrame2 v2.07 API Specification" ^
-doctitle "iFrame2<sup><font size=-2>TM</font></sup> v2.07 API Specification" ^
-header "<b>iFrame2</b>
<font size=-1>v2.07</font>" ^
-bottom "<font size=-1><a href=mailto:jhamlin@dynamic-info.com?SUBJECT=iFrame2>Submit a bug or feature</a>
iFrame is a trademark or registered trademark of Dynamic Information Systems.
2000 Dynamic Information Systems, 505 Waterford Suite 100, 505 N Hwy 169, Minneapolis MN, 55441
All Rights Reserved.</font>" ^
-d %docsDir% ^
-sourcepath %sourceDir% ^
-link http://java.sun.com/j2se/1.3/docs/api ^
-link http://java.sun.com/products/servlet/2.2/javadoc ^
-link http://java.sun.com/xml/docs/api ^
-link http://java.sun.com/products/javamail/1.2/docs/javadocs ^
-link http://java.sun.com/products/javabeans/glasgow/javadocs ^
@%TEMP%\%project%_packages.txt
del %TEMP%\%project%_packages.txt
[1975 byte] By [
jchamlin] at [2007-9-27 1:33:37]
I tried this, and I could get it to work for java.lang.String.Using the same syntax that worked for @see java.lang.String, the following all failed for me@see java.lang.System@see java.lang.Thread@see java.lang.Long I also use 1.3.1
You're probably experiencing the well-understood but
little recognized problem that a class must be either
imported or declared in your source code for a link to work.
The @see reference is not enough by itself to find the class,
even though you are using -link.
The workaround is to add this import statement:
import java.lang.System;// workaround to enable @see hyperlink
This is documented in the Javadoc documentation:
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html#howaclassmustbereferenced
and in the Javadoc FAQ:
http://java.sun.com/j2se/javadoc/faq.html#missinglinks
You can vote for us to fix it by voting for ths feature request:
4662658: With -link, all @see/@link tags should create links to excluded classes
http://developer.java.sun.com/developer/bugParade/bugs/4662658.html
-Doug Kramer
Javadoc team
Thanks. I did eventually try that (importing java.lang.System) and it worked. I think that javac and javadoc should behave the same way. Here are my thoughts on the matter:
I think that the javadoc generator should behave the same as the javac compiler, explicitly knowing that java.lang.* should be available without requiring an import statement or a full package statement on the @link or @see tag. Example: @see System#currentTimeMillis should work implicitly.
As well, the javadoc should know the well known location of the Sun provided Javadoc for the version of the javadoc executable, and should implicitly have a -link statement to the Sun provided Javadoc for the standard classes unless an alternate -link or -linkoffline is provided. (i.e. first search the user provided -link and -linkoffline, and if still not found, try the implicit link included with the javadoc executable). Example: the javadoc from the JDK 1.3.1_02 distribution should implicitly have -link http://java.sun.com/j2se/1.3/docs/api
-J.C.
> Example: @see System#currentTimeMillis should work implicitly.
This has been fixed in 1.4.0. This works implicitly only for java.lang.*.
See:
http://java.sun.com/j2se/1.4/docs/tooldocs/windows/javadoc.html#howaclassmustbereferenced).
> Example: the javadoc from the JDK 1.3.1_02 distribution should implicitly have -link http://java.sun.com/j2se/1.3/docs/api
I suppose that might satisfy most needs. It seems there would need
to be a way to turn off those implicit links.
Please submit that as a request, as instructed at:
http://java.sun.com/j2se/javadoc/faq.html#submitbugs
-Doug Kramer
Javadoc team
> This has been fixed in 1.4.0. This works implicitly
> only for java.lang.*.
Are you sure? I'm using 1.4.0, I have explicitly imported java.lang.System in my code and still @see System#currentTimeMillis() does not work. Here is my cmd line...
javadoc -d curatorjavadocs ^
-link http://docs/java/j2sdk1.4.0/api ^
-link http://docs/java/log4j/api ^
-link http://docs/java/tomcat-docs/servletapi ^
-link http://docs/java/xerces/apiDocs ^
-link http://docs/java/jdmk/docs/locale/C/api ^
-link http://docs/java/j2ee1.3/api ^
-link http://www.jspsmart.com/liblocal/docs/en/jspsmartupload/help/doc ^
-use -splitindex -author -version ^
-windowtitle "Curator v3.0" ^
-linksource -breakiterator -quiet ^
-subpackages com.digimob.curator
I've tried NOT importing System, specifying it explicitly in the @see tag, etc. with no success. I'm also having the same trouble with {@link}.
Regards,
Gavin
Do you have the docs you're linking to on a webserver named http://docs? That is, if you type this URL into a browser, does it open the API docs?
http://docs/java/j2sdk1.4.0/api
Often terminal windows don't have direct http access to web pages. In that case, you would need to use -linkoffline instead
of -link.
Do any of your links work, or does only java.lang.System fail?
The following works for me to create links to Math, String and Integer, so should work for System. It uses 1.4.0.
% more p/Test.java
package p;
/**
* These links should work because java.lang.* is implicitly imported:
* {@link java.lang.Mathjava.lang.Math} link
* {@link java.lang.String java.lang.String} link
* {@link java.lang.Integer java.lang.Integer} link
*/
public class Test {
}
% ls -l package-list
-rw-r--r--1 dkramer green2695 Jan 30 14:31 package-list
% javadoc -d docs-1.4.0 \
-linkoffline http://java.sun.com/j2se/1.3/docs/api . \
p
-Doug Kramer
Javadoc team
> Do you have the docs you're linking to on a webserver
> named http://docs? That is, if you type this URL into
> a browser, does it open the API docs?
>
> http://docs/java/j2sdk1.4.0/api
Yes, I set up an internal repository for javadocs so we have faster access to them
> Do any of your links work, or does only
> java.lang.System fail?
any @see or @link tags that reference an external javadoc fail. However, links appear for correctly for method and type declarations that reference an object that is externally javadoc'ed.
For instance, I have the following:-
import javax.servlet.http.HttpServletRequest;
**
* Substituted for the current session ID.
* @see HttpServletRequest#getRequestedSessionId()
*/
public static final String SESSION_ID = "SESSION_ID";
A link is generated to String but not to HttpServletRequest#getRequestedSessionId() even though both are in external javadocs that have been referenced with -link and both have been HttpServletRequest has been imported. I've tried fully qualifying HttpServletRequest in the @see tag itself and it still doesn't work.
Regards,
Gavin
Yes, this appears to be a bug with how @see (and {@link}) are treated. I'll see what our doclet programmer has to say.BTW, it appears there's a typo in the doc comment -- the leading slash (/**) is missing.-Doug KramerJavadoc team
Another thought -- what is your classpath set to?
Is javax.servlet.http.HttpServletRequest on your classpath?
Do you get any errors that this class could not be found?
BTW, String might be treated differently, since it is built into Java.
If none of the external links to classes outside java.* work, please try using -linkoffline just to humor me, at :-)
In the meantime, I've sent off email to the doclet programmer.
-Doug Kramer
> BTW, it appears there's a typo in the doc comment -- the leading slash (/**) is missing.
Oops, perhaps I should be a bit more accurate with my cut & paste :-)
> Is javax.servlet.http.HttpServletRequest on your
> classpath?
Yes, it is
> Do you get any errors that this class could not be
> found?
No
> BTW, String might be treated differently, since it is
> built into Java.
> If none of the external links to classes outside
> java.* work, please try using -linkoffline just to
> humor me, at :-)
Did the following:-
javadoc -d curatorjavadocs ^
-linkoffline http://docs/java/j2sdk1.4.0/api http://docs/java/j2sdk1.4.0/api ^
-linkoffline http://docs/java/log4j/api http://docs/java/log4j/api ^
-linkoffline http://docs/java/tomcat-docs/servletapi http://docs/java/tomcat-docs/servletapi ^
-linkoffline http://docs/java/xerces/apiDocs http://docs/java/xerces/apiDocs ^
-linkoffline http://docs/java/jdmk/docs/locale/C/api http://docs/java/jdmk/docs/locale/C/api ^
-linkoffline http://docs/java/j2ee1.3/api http://docs/java/j2ee1.3/api ^
-linkoffline http://www.jspsmart.com/liblocal/docs/en/jspsmartupload/help/doc http://www.jspsmart.com/liblocal/docs/en/jspsmartupload/help/doc ^
-use -splitindex -author -version ^
-windowtitle "Curator v3.0" ^
-linksource -breakiterator -quiet ^
-subpackages com.digimob.curator
but sadly @link and @see still did not work for external referenced URLs
Gavin
I discovered we do have a bug submitted stating external links with -link don't work. We will fix this for 1.4.1:
http://developer.java.sun.com/developer/bugParade/bugs/4652655.html
Perhaps this will solve your problem.
.....
When using -linkoffline, you must supply a second argument to each occurrence, which is the directory path to the package-list file. This means you must copy the package-list file located,
for instance, at
http://docs/java/j2sdk1.4.0/api http://docs/java/j2sdk1.4.0/api/package-list
to a location reachable by the shell where you're running javadoc.
If this is the current directory, then pass in the current directory (.)
as the second argument to -linkoffline:
javadoc -d curatorjavadocs ^
-linkoffline http://docs/java/j2sdk1.4.0/api . ^
etc.
You could try it on just one or two packages.
-Doug Kramer
