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

[Jan Lahoda]

Hi,

Looks good to me.

Jan

On 16.11.2018 21:10, Jonathan Gibbons wrote:
> 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
>
>