Hi there,
Can anyone tell me how to inherit the javadoc comments from interfaces in the standard Java library please?
I have an implementation of javax.naming.Context and wanted the comments from the original interface to appear in my javadoc.
I added src.zip from the sdk to the -sourcepath
Any ideas?
I am using J2SE 1.4.0 for Windows.
Many thanks
Roger
Inheriting a comment from an interface method to a method in a class that implements that interface should be automatic if the class's method has no comment. It must also be true that the overridden method is a member of a documented class, and not an external referenced class for the doc comment to actually be available to copy.
In your example, Context is a referenced class, not one being documented, so its doc comment is not available to Javadoc.
Javadoc cannot interpret .zip or .jar files on the -sourcepath. To inherit the comment, you would have to unzip src.zip and add the source file javax/naming/Context.java to the list of packages and source files to document.
This is documented at:
http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#inheritingcomments
You could submit a request for a new option such as -inheritdocpath that points to source files that javadoc should import only for inheritance purposes. Do this at http://java.sun.com/j2se/javadoc/faq/index.html#submitbugs
This would be a neat feature. (It's best if such requests come directly from developers.)
-Doug Kramer
Javadoc team
Dear Doug,
Thanks for your help, but I am not quite there yet.
It is partly the syntax with directory names with spaces and where to use quotes, dots, colons etc. that is throwing me.
The src.zip is now unzipped to "d:\java\Sun JDK\jdk1.4.0\src", so the directory .\javax\naming\ comes directly below this.
I am calling com.sun.tools.javadoc.Main.execute() with the following String[] argument...(each line is a different array element)
-private
-d
d:\My Library\api\
-author
-version
-use
-splitindex
-sourcepath
d:\My Library
d:\Java\Sun JDK\jdk1.4.0\src
@d:\My Library\api\packagelist.txt
where the source paths are directly below "d:\My Library" and packagelist.txt has javax.naming.Context appended to it.
This gives 2 errors:
javadoc: No source files for package d:\Java\Sun JDK\jdk1\4\0\src
javadoc: No source files for package javax\naming\Context
It isn't just the dots in the jdk1.4.0 turning to slashes.
I tried putting the source files on d:\Java\src it gave similar errors.
What am I doing wrong?
Many thanks
Roger
Other than its options, Javadoc can only accept two kinds of arguments: source filenames (paths with slashs that end with .java) and package names (contain dots, not slashes). Your command is mixing the two.
The -sourcepath option sets the path only for package names, not for source filenames. The command is attempting to use -sourcepath to set the path for Context.java, which is not a package. (I know this is counter-intuitive -- the option should perhaps be named -packagesrcpath)
The packagelist.txt file should contain:
d:\java\Sun JDK\jdk1.4.0\src\javax\naming\Context.java
and the arguments should not contain d:\Java\Sun JDK\jdk1.4.0\src:
-private
-d
d:\My Library\api\
-author
-version
-use
-splitindex
-sourcepath
d:\My Library
@d:\My Library\api\packagelist.txt
Try that and let me know what happens.
-Doug Kramer
Javadoc team
Hi Doug,
Thanks for the help. It's better, but not right yet.
The space between "Sun" and "JDK" in the path of Context.java are throwing it, so I still get 2 errors:
error: cannot read: JDK\jdk1.4.0\src\javax\naming\Context.java
javadoc: No source files for package d:\Java\Sun
This is the last problem as it works if I move Context.java to d:\Java\src\ (i.e. a path without spaces anywhere).
Is there a way past the last hurdle?
Many thanks
Roger
That should be simple to fix. Any string that contains a space must have quotes around it. Sorry to not have noticed that.
The packagelist.txt file should contain:
"d:\java\Sun JDK\jdk1.4.0\src\javax\naming\Context.java"
It appears you don't need quotes around the following strings, but I am showing the quotes here just for completeness:
-private
-d
"d:\My Library\api\"
-author
-version
-use
-splitindex
-sourcepath
"d:\My Library"
@"d:\My Library\api\packagelist.txt"
-Doug Kramer
Javadoc team
Dear Doug,
Thanks, now it works, but it took one more trick!
If I put quotes around ...\Context.java in packagelist.txt, it kills all the back slashes, as well as turning the leading "n" of naming into a '\n' and throwing a line:
Loading source file d:JavaSun JDKjdk1.4.0srcjavax
amingContext.java...
error: cannot read: d:JavaSun JDKjdk1.4.0srcjavax
amingContext.java
So I need to escape the backslashes in the text file too.
Strange but true (or so it seems to me).
This leads to the slightly bizarre code with quadruple "\" escaping:
out.write(("\"d:\\\\Java\\\\Sun JDK\\\\jdk1.4.0\\\\src\\\\javax\\\\naming\\\\Context.java\"\n").getBytes());
By the way, quotes around the String[] parameters do not appear to be permitted. If included, it says it cannot read the source files / package list file.
Clearly this would be if different calling javadoc from the command line.
If there is a more elegant approach I would be interested to know, but I am pleased that it does what I wanted.
Many thanks for your help
Roger
hey folks;
do you know if this request was submitted; or is this something perhaps now in 1.4?
we're using 1.3, and really would like to inherit the docs for classes like java.sql.Resultset, but don't want to have to include those j2se classes in our javadocs.
is there any other way around copy/pasting? is there some possibility with a doclet?
thanks in advance;
-m
This thread is getting too long. I gather you're referring to my
suggestion:
You could submit a request for a new option such as
-inheritdocpath that points to source files that javadoc
should import only for inheritance purposes.
This would be a neat feature.
Yes, this has been submitted as feature 4707291:
http://developer.java.sun.com/developer/bugParade/bugs/4707291.html
It might make sense to just load any classes on -sourcepath
to get their comments.
We're thinking of longer-term solutions where we would make it
easy to generate stub files to pass around or XML files that
could eventually be sucked into javadoc.
-Doug Kramer
Javadoc team
