Problem

Eclipse meldet fehlerhafte Javadoc-Verweise als Fehler, darunter mehr als 100 Fehlalarme, die javac und javadoc akzeptieren:

• Invalid member type qualification: ein innerer Typ, über seinen importierten äußeren Typ verwiesen, z. B. {@link EditorFactory.Config#getSelectionDialogThreshold()}.
• Invalid reference in package-info.java: ein einfacher Name eines Typs aus demselben Paket.

Für diese Meldungen gibt es in Eclipse keinen eigenen Schalter, und mit jeder Änderung kommen neue hinzu.

Umgekehrt prüft der Maven-Build weder Javadoc-Verweise noch ungenutzte Imports, beides meldet nur Eclipse:

• javac ignoriert Javadoc, und der TLDoclet gibt einen nicht auflösbaren Verweis kommentarlos als <code> aus. Ein kaputter {@link} bleibt so unbemerkt, etwa nach dem Umbenennen oder Entfernen einer Klasse.
• javac kennt keine Warnung für ungenutzte Imports.

Lösung

Eclipse

In allen .settings/org.eclipse.jdt.core.prefs, die Javadoc prüfen, steht nun org.eclipse.jdt.core.compiler.problem.invalidJavadoc=warning statt error. Die Meldungen bleiben sichtbar, verhindern aber keinen Eclipse-Build mehr.

Maven: Javadoc-Verweise

Das Root-POM tl-parent-all übergibt javac die neue Property tl.javac.doclint:

• Default ist -Xdoclint:none. Kundenanwendungen ändern damit nichts, können die Prüfung aber durch Setzen der Property einschalten.
• Engine-Module setzen sie auf -Xdoclint:reference/private: über tl-parent-core-internal und tl-parent-app-internal, Module mit öffentlichem Parent (GWT-Clients, Build-Tools, basic.core, basic.shared u. a.) direkt in ihrem POM. Ausgenommen ist eingebetteter Fremdcode (ext.*).

Ein nicht auflösbarer Verweis ({@link}, @see, @throws, {@value}) lässt dann den Compile fehlschlagen, auch in privaten Membern und in Testcode. Die Prüfung folgt den Regeln von javac und meldet deshalb die oben genannten Eclipse-Fehlalarme nicht.

Maven: ungenutzte Imports

Das Root-POM führt den maven-checkstyle-plugin mit der einzigen Regel UnusedImports in der Phase validate aus, gesteuert über die neue Property tl.unused-imports.skip:

• Default ist true, Kundenanwendungen bleiben unberührt.
• Dieselben Engine-Module, die tl.javac.doclint setzen, setzen sie auf false.

Ein Import, der nur im Javadoc benutzt wird, zählt wie in Eclipse als benutzt. Testcode wird mitgeprüft, module-info.java nicht (Checkstyle kann Moduldeklarationen nicht parsen).

Einschränkung: Checkstyle erkennt einen Import nicht, der nur in einem @see mit umbrochener Parameterliste oder in einem Javadoc vor einem weiteren /* */-Kommentar benutzt wird. In solchen Fällen den Typ im @see voll qualifizieren bzw. den Kommentar über das Javadoc stellen.

Redundante Typargumente (Eclipse: Redundant specification of type arguments) prüft weiterhin nur Eclipse. PMDs Regel UseDiamondOperator wurde verworfen: Sie meldet auch Raw Types und anonyme Klassen (rund 1100 Stellen) und bildet die Eclipse-Prüfung nicht nach.

Bereinigung

Die Javadoc-Prüfung fand 26 bestehende Fehler, die alle behoben sind, u. a.:

• Verweise auf nicht mehr existierende Klassen und Member (ConfiguredModelOptions, AbstractFragmentOverlay, #visitItemEvent, #parentRatio, #A2).
• Veraltete Signaturen (ViewExecutabilityRules#build) und generische Parameter statt ihrer Erasure.
• Per Static-Import sichtbare Konstanten mit # verwiesen (#H2, #VOID_ELEMENTS).
• {@value} auf Nicht-Konstanten, @throws für nicht geworfene Exceptions.

Dazu sind die bestehenden ungenutzten Imports und redundanten Typargumente entfernt.

Eclipse-Workaround

In EditPersonContactComponent und SAPFileSupplierDataImporter meldet Eclipse ''Type mismatch: cannot convert from TLStructuredType to TLClass'' für tType(): javac nimmt das TLClass-Ergebnis von AttributedObject.tType(), Eclipse die über AbstractTLObject geerbte Variante TLObject.tType(). Ein kommentierter Cast auf TLClass umgeht das.

Hinweis für Entwickler

Ein kaputter Javadoc-Verweis oder ein ungenutzter Import in einem Engine-Modul bricht ab jetzt den lokalen Build und den CI-Build.