RFR: 8267708: Remove references to com.sun.tools.javadoc.**

[Jonathan Gibbons]

On Tue, 25 May 2021 17:32:11 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Although the `com.sun.tools.javadoc.**` packages were removed in JDK-8215584, some references to them remain, mainly in the form of links in doc comments. Some of those links refer to classes that never existed, which I reckon is due to a typo; for example, this reference
> 
>     com.sun.tools.javadoc.ClassDocImpl#findField
> 
> should've looked like this
> 
>     com.sun.tools.javadoc.main.ClassDocImpl#findField
> 
> Grep showed that some tests also use `com.sun.tools.javadoc` and some other extinct packages. However, it is unclear if those "references" should also be removed:
> 
> 1. https://github.com/openjdk/jdk/blob/739769c8fc4b496f08a92225a12d07414537b6c0/test/langtools/tools/javac/NoStringToLower.java#L60-L74
> 2. https://github.com/openjdk/jdk/blob/739769c8fc4b496f08a92225a12d07414537b6c0/test/langtools/tools/javac/T8003967/DetectMutableStaticFields.java#L73-L85

The package references in the two tests you found should be updated to use `jdk.javadoc`.  That's already present for #2, so just delete the old package in #2, and change the package in #1.

src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java line 627:

> 625:     }
> 626: 
> 627:     /** @see com.sun.tools.javadoc.ClassDocImpl#findField */

Is there an equivalent new-style method that should be used instead?

src/jdk.compiler/share/classes/com/sun/tools/javac/util/Log.java line 319:

> 317:      *      com.sun.tools.javadoc.Main.execute(String programName,
> 318:      *          PrintWriter errWriter, PrintWriter warnWriter, PrintWriter noticeWriter,
> 319:      *          String defaultDocletClassName, String... args)

It is generally bad form to have `@Deprecated` without `@deprecated`. In this case, separate ongoing work to cleanup `Messager` will eventually mean we can remove the method altogether.

If you really want to remove the reference to the old code, the `@deprecated` comment should be updated to "Still in use by javadoc's Mesager class." or some such.

-------------

Changes requested by jjg (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/4192