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

Javadoc does not link correctly to other Javadoc sites that force index.htm

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Closed
    • Priority: P4
    • Resolution: Not an Issue
    • Affects Version/s: 1.3.1
    • Fix Version/s: None
    • Component/s: tools
    • Labels:

      Description



      Name: boT120536 Date: 08/29/2001


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

      Suppose you wish to link to generated Javadoc from a site that forces you to
      type in index.htm or index.html for the main page of it's Javadoc (i.e. it
      doesn't let you just type the URL without the filename index.htm or index.html
      at the end of the URL). Javadoc assumes index.htm is a directory and makes all
      links underneath that directory. Both -link and -linkoffline will not work
      correctly.

      The -link option will fail to find the package-list file because it exists at
      the same directory level as index.htm (and not inside a directory called
      index.htm).

      The -linkoffline option will run, but all the generated links will point to
      pages underneath a directory index.htm. All the data put into the generated
      Javadoc is correct (such as class, method, and attribute names), but the links
      to the code are incorrect because Javadoc assumes the URL in -link or
      -linkoffline does not end in a filename.

      Suppose you wish to link to the JUnit Javadoc in your own code. JUnit's javadoc
      code exists at:
      http://www.junit.org/junit/javadoc/3.7/index.htm
      You CANNOT type in the URL:
      http://www.junit.org/junit/javadoc/3.7
      and get the data to display because of how their site was set up. If you could,
      this site would work correctly with Javadoc.

      So suppose you wish to generate your Javadoc with the command:
      javadoc -link http://www.junit.org/junit/javadoc/3.7/index.htm @packages

      This will fail because it will be unable to locate JUnit's package-list file
      which is at:
      http://www.junit.org/junit/javadoc/3.7/package-list

      Javadoc is trying to look for package-list at:
      http://www.junit.org/junit/javadoc/3.7/index.htm/package-list



      Next you try to type the command as follows:
      javadoc -link http://www.junit.org/junit/javadoc/3.7 @packages

      This will also fail because JUnit's Web site will not resolve that URL without
      the explicit index.htm filename. So Javadoc can't find index.htm. That is not a
      Javadoc flaw. I am just showing that is not an available option right now.



      Next you try to work around this by trying -linkoffline.
      javadoc -linkoffline http://www.junit.org/junit/javadoc/3.7/index.htm
      http://www.junit.org/junit/3.7/package-list @packages

      This command actually runs and generates Javadoc. But the problem is that all
      the links to JUnit documentation within the Javadoc generated files are
      incorrect. For instance, a link to junit.framework.Assert should be:
      http://www.junit.org/junit/3.7/junit/framework/Assert.html

      But is incorrectly generated as:
      http://www.junit.org/junit/3.7/index.htm/junit/framework/Assert.html


      So none of the JUnit links in the generated files will actually point to the
      correct URL's. What needs to be done with Javadoc, is for it to look to see if
      the URL in a -link or -linkoffline command is actually a file like index.htm or
      index.html. If it is, it should be able to find package-list at the same
      directory level in the -link command. It should also generate correct links
      without the index.htm in them (except for any links to the main page, which
      SHOULD retain that filename. i.e. use the filename if pointing to a filename
      such as that main page which DOES require index.htm, but don't use the filename
      if we are talking about the directory the files exist within.).

      I have sent in a request to the site hosting JUnit's documentation, so it is
      possible this situation will change. But for now at least, this is a good
      example to look at as JUnit is quite a common tool to Java testing. I would
      assume other sites that people may want to link their Javadoc to would also have
      this situation.
      (Review ID: 130694)
      ======================================================================

        Attachments

          Activity

            People

            Assignee:
            dkramersunw Douglas Kramer (Inactive)
            Reporter:
            bonealsunw Bret O'neal (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: