RFR: JDK-8213956: javadoc crash using {@index} in doc-files file

[Jonathan Gibbons]

Please review a moderately simple fix to a javadoc crash that was caused 
by using {@index} in an HTML file in a doc-files subdirectory.

The root cause is that the standard doclet uses custom elements when 
processing HTML files in doc-files subdirectories and any overview 
file.  These custom elements were causing the viistUnknown to be called 
in a visitor that is used while processing {@index} tags.  The basic fix 
is therefore to implement visitUnknown.

  * */TagletWriterImpl:/* The "hard" part of the fix was determining the
    URL for the target of the search link, and in particular,
    determining the path in that URL. However, once found, the solution
    was easy: the taglet writer has access to the enclosing HTML writer,
    which knows the file that is being written.  Since this is true for
    the use of {@index} in the documentation for all elements, we can
    simplify the visitor by setting the URL  outside the visitor. And
    then, since many of the visit methods end up having the same
    functionality as the default action (i.e. using the fully qualified
    name of the element), we can delete those overriding methods and use
    the defaultAction method instead.

    The changes also fix another minor issue: the simple name was used
    instead of the fully qualified name of the package for the "holder"
    of the search item. See line 437 in the "before" version of
    TagletWriterImpl.java

  * */HTMLDoclet:/* Although the crash was in doc-files, the code should
    support {@index} in the overview file. But for that to work, the
    index files must be generated after the overview file has been
    processed.

  * /*DocFilesHandlerImpl:*/ Fix the reporting of the file being
    generated: it was printing the default .toString() and not the
    actual path of the file.

  * /*New test: */the new test verifies the use of {@index} in
    package-info.java files, files in doc-files subdirectories, and in
    an overview file. Since {@systemProperty} is a related new feature,
    the test also verifies the use of {@systemProperty} in
    package-info.java and files in doc-files subdirectories. (The tag is
    not permitted in overview files.)

All javadoc tests pass; in addition, the .html files in JDK API 
documentation are not affected by the cleanup, and compare the same, 
before and after.

-- Jon


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20181116/801ad3ff/attachment.html>