Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4905399

doc-files sometimes not copied by javadoc

    XMLWordPrintable

    Details

      Description

      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)
      ======================================================================

        Attachments

          Activity

            People

            Assignee:
            jhosunw Jamie Ho (Inactive)
            Reporter:
            rmandalasunw Ranjith Mandala (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: