[ttools] com.sun.javadoc was removed in JDK 17

[olebole]

Hi Mark,

I got the bug Debian#1025440 that ttools does not compile anymore on Debian. It turns out that this is due to the import of com.sun.javadoc classes in the uk.ac.starlink.ttools.build package:

build:
    [mkdir] Created dir: /build/1st/starjava-ttools-3.4.7/build/classes
    [javac] Compiling 955 source files to /build/1st/starjava-ttools-3.4.7/build/classes
    [javac] /build/1st/starjava-ttools-3.4.7/src/main/uk/ac/starlink/ttools/build/FullXmlDoclet.java:3: error: package com.sun.javadoc does not exist
    [javac] import com.sun.javadoc.ClassDoc;
    [javac]                       ^
[...]

The com.sun.javadoc API was replaced with jdk.javadoc.doclet and deprecated some time ago and is now removed with JDK 17, so probably the uk.ac.starlink.ttools.build package needs a rewrite.

[mbtaylor]

@olebole , thanks for bringing that to my attention. I'll have a think about what to do. In the mean time, do you happen to know if those classes are available in a debian-licencing-friendly form anywhere? If you don't know, I can go looking myself.

[olebole]

Do you mean the old API or the new one? I am afraid that com.sun.javadoc is finally gone, so for the meantime I could only patch that out (my understanding is that its use is the creation of the help pages for JEL functions).

[mbtaylor]

Either or both ... I thought you were saying that jdk.javadoc.doclet had been removed, but re-reading your comment I see you mean jdk.javadoc.doclet is still present. I can take a look at that, it should be OK if it's Java8 compatible, but if not (and given that it seems to cater for modules maybe it won't be) that might be a problem.

[olebole]

jdk.javadoc.doclet was introduced in Java 9, https://openjdk.org/jeps/221

[mbtaylor]

This is going to be a bit of a pain to resolve, unless I move to building with Java 9+, which I don't particularly want to do. I will tackle it at some point, but it won't be immediately. I guess in the mean time that means that the debian build will just have to avoid running the relevant doclets, so the auto-generated documentation (of expression language functions) will be somewhat deficient in the debian version.

[mbtaylor]

@olebole I have reworked the relevant classes and there are now two alternative doclet implementations that can be used at build time for generating this documentation, one for Java8 and one for Java17+ (in between, either will do). See commits a2d8b5e^.. e90c092. The commit messages should tell you what you need to know, but get back to me if you want more explanation or anything else. Thanks for making me aware of this issue.