Name: rmT116609 Date: 08/12/2003


FULL PRODUCT VERSION :
% java -version
java version "1.4.2-beta"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2-beta-b19)
Java HotSpot(TM) Client VM (build 1.4.2-beta-b19, mixed mode)

java version "1.4.2"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2-b28)
Java HotSpot(TM) Client VM (build 1.4.2-b28, mixed mode)


FULL OS VERSION :
Linux 2.4.20-xfs #2 SMP Fri Feb 21 15:57:53 GMT 2003 i686 unknown

A DESCRIPTION OF THE PROBLEM :
Javadoc does not copy the doc-files subdirectory under
some directory setups. I am NOT referring to
recursive copies of subdirectories of doc-files, but to
doc-files itself.

Below I show command lines runs with -sourcepath
set in different ways.
1) absolute path to machine local directory (works)
2) relative path (in fact .) to NFS mounted directory (works)
3) absolute path to the same NFS mounted directory (works NOT)

Note the diff at the end which should prove that the two directories
I am referring to have identical content.

I can not say if the NFS mount plays a crucial role. It is just
the only difference between the two I can think of. Well, the
NFS mounted dir also goes through one or two soft-links.



STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
As described above, I can only guess what the proper setup
must be to reproduce the bug. I file it nevertheless, because I expect more people to come up with this, which may report differnt setups.



EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The directory doc-files should always be copied by javadoc.

ACTUAL -
Below you see the command lines and output produced by several
different runs of javadoc which should actually all do the same thing.
All commands where run in the same directory.
I put some comments in between.

## Prove that we have two identical directories:
% diff -r jfa ~/tmp/jfa

## The above produces no output. Now have a look at the
## files found there:
% find jfa
jfa
jfa/Bla.java
jfa/doc-files
jfa/doc-files/CVS
jfa/doc-files/CVS/Root
jfa/doc-files/CVS/Repository
jfa/doc-files/CVS/Entries
jfa/doc-files/resyntax.html

## The content of jfa/Bla.java is trivial.
% cat jfa/Bla.java
package jfa;
/**
 * an example class.
*/
public class Bla {}

## Now the runs of javadoc with sourcepath set to different
## paths. I filter the output slightly to trim it a bit. Error
## messages would appear, only the lines 'Generating ...' are dropped.

## sourcepath set to absolute path on local disk, works, see last
## line of output
javadoc -d ~/tmp/blarg -sourcepath ~/tmp jfa 2>&1 |grep -v Generating
Loading source files for package jfa...
Constructing Javadoc information...
Standard Doclet version 1.4.2-beta
Building tree for all the packages and classes...
Building index for all the packages and classes...
Building index for all classes...
Copying file /homes/kirsch/tmp/jfa/doc-files/resyntax.html to directory /homes/kirsch/tmp/blarg/jfa/doc-files...


## sourcepath relative to NFS mounted disk, works:
% javadoc -d ~/tmp/blarg -sourcepath . jfa 2>&1 |grep -v Generating
Loading source files for package jfa...
Constructing Javadoc information...
Standard Doclet version 1.4.2-beta
Building tree for all the packages and classes...
Building index for all the packages and classes...
Building index for all classes...
Copying file ./jfa/doc-files/resyntax.html to directory /homes/kirsch/tmp/blarg/jfa/doc-files...

## sourcepath absolute to NFS mounted disk, actually the
## identical directory as above.
javadoc -d ~/tmp/blarg -sourcepath `/bin/pwd` jfa 2>&1 |grep -v Generating
Loading source files for package jfa...
Constructing Javadoc information...
Standard Doclet version 1.4.2-beta
Building tree for all the packages and classes...
Building index for all the packages and classes...
Building index for all classes...

## NO, I did not just forget to copy the last line of output. It
## is not there!



% java -version
java version "1.4.2"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2-b28)
Java HotSpot(TM) Client VM (build 1.4.2-b28, mixed mode)

## The example directory structure
% find bla
bla
bla/jfa
bla/jfa/doc-files
bla/jfa/doc-files/CVS
bla/jfa/doc-files/CVS/Root
bla/jfa/doc-files/CVS/Repository
bla/jfa/doc-files/CVS/Entries
bla/jfa/doc-files/resyntax.html
bla/jfa/Bla.java

## Now I run javadoc and this way it works:
% javadoc -d jfa_doctest -sourcepath /homes/kirsch/work/bla jfa|grep -v
Generating
Loading source files for package jfa...
Constructing Javadoc information...
Standard Doclet version 1.4.2
Building tree for all the packages and classes...
Building index for all the packages and classes...
Building index for all classes...
Copying file /homes/kirsch/work/bla/jfa/doc-files/resyntax.html to directory
jfa_doctest/jfa/doc-files...

## Note the last line, doc-files copied nicely. Now I change the name of
## the parent directory of jfa from bla to jfa:
% cd ~/work/; mv bla jfa; find jfa
jfa
jfa/jfa
jfa/jfa/doc-files
jfa/jfa/doc-files/CVS
jfa/jfa/doc-files/CVS/Root
jfa/jfa/doc-files/CVS/Repository
jfa/jfa/doc-files/CVS/Entries
jfa/jfa/doc-files/resyntax.html
jfa/jfa/Bla.java

## Back to tmp, I run the javadoc again and now it does not work:
% cd ~/tmp; javadoc -d jfa_doctest -sourcepath /homes/kirsch/work/jfa
jfa|grep -v Generating
Loading source files for package jfa...
Constructing Javadoc information...
Standard Doclet version 1.4.2
Building tree for all the packages and classes...
Building index for all the packages and classes...
Building index for all classes...

## The line about copying doc-files is indeed missing. I did not just forget
## to copy them to the bug report.

I renamed the parent directory of the package from bla, which works, to
several differnt names. A small selection:
xjfa, jfax,jfabla,AjfaA -- don't work
xxx, yyy,afj -- work


REPRODUCIBILITY :
This bug can be reproduced always.

CUSTOMER SUBMITTED WORKAROUND :
Use relative paths for -sourcepath or have your
source package files on a local disk. The last is
just a guess derived from the above examples.
(Incident Review ID: 191124)
======================================================================