Error with doc-files - please read me
I am not a JavaDoc expert, and I'm having a problem with the doc-files feature. I read that you can place a sub-directory named "doc-files" in your source code directory. The purpose of this sub-directory is to hold additional (supplemental) files for your JavaDoc comments in your source code to reference as needed. For example, you can put image files that are referenced from your JavaDoc comments.
Anyway, javadoc is supposed to copy the files in these sub-directories to an indentical sub-directory in your generated html area. My supplementary file happens to be standard html, and javadoc did copy this file to the right place in the generated html area. However, if I modifiy my supplementary file, then re-run JavaDoc, it not only neglects to get the new modifications, but it also clobbers the supplementary file that it already put in the html area from the original run. Now, there is a broken link in my JavaDoc comment that cannot find the supplementary file.
If I erase the "doc-files" sub-directory that javadoc created in the html area, then re-run javadoc, it works again.
What is going on here?
It appears that you've discovered a subtle and important bug. Rather than overwriting an exisiting file (standard.html), it only goes halfway -- it deletes the file in the destination directory but then fails to copy the new one there.
Which version of javadoc are you running? If we can reproduce this on 1.4.0, we will fix it, probably for 1.4.2 (1.4.1 is frozen).
Please submit this as a bug using the instructions at:
http://java.sun.com/j2se/javadoc/faq/index.html#submitbugs
You'll need to describe the steps to reproduce it, which sound simple.
Just curious -- I wonder if you run javadoc twice, if the first time it will clobber the destination file (which is the bug) and the second time it will copy the modified file there.
-Doug Kramer
Javadoc team
I am using SDK 1.3.1. I would like to use SDK 1.4, but it has a huge bug with rendering images on Swing components (buttons). So, we are forced to deliver our product with 1.3.1.
I'll try to remember to file the JavaDoc bug later when I get some time. However, you may have already fixed this in SDK 1.4.0.
> It appears that you've discovered a subtle and
> important bug. Rather than overwriting an exisiting
> file (standard.html), it only goes halfway -- it
> deletes the file in the destination directory but then
> fails to copy the new one there.
>
> Which version of javadoc are you running? If we can
> reproduce this on 1.4.0, we will fix it, probably for
> 1.4.2 (1.4.1 is frozen).
>
> Please submit this as a bug using the instructions
> at:
>
> http://java.sun.com/j2se/javadoc/faq/index.html#submitb
> gs
>
> You'll need to describe the steps to reproduce it,
> which sound simple.
>
> Just curious -- I wonder if you run javadoc twice, if
> the first time it will clobber the destination file
> (which is the bug) and the second time it will copy
> the modified file there.
>
> -Doug Kramer
> Javadoc team
I'm familiar with all the bug fixes in 1.4.0, and this is not among them. So it would not be fixed unless it happened to be "accidentally" fixed.
I just tried reproducing the bug, and could not reproduce
it with either 1.3.1 or 1.4.0. I created a file com/package1/doc-files/test.html, ran Javadoc, ensured the page was in the destination, then modified test.html by adding a word to it, re-running and sure enough the modified file was in the destination. So I guess I'll need your exact setup and files.
Is is possible you have delete but not write permissions in the destination directory? Read only files can be deleted but not
edited.
-Doug Kramer
Javadoc tool
