JDK 28 schlaegt ein JavaDoc-Tag fuer Hinweise und Warnungen vor
Victoria Shinder2 Min. LesezeitDie OpenJDK Quality Group hat die Projekte ihres Quality-Outreach-Programms vorgewarnt: JDK 28 schlaegt ein neues JavaDoc-Tag @note vor, mit dem Hinweise und Warnungen direkt in der API-Dokumentation markiert werden. Der Beitrag stammt von Billy Korando, datiert auf den
- September 2026: https://inside.java/2026/09/23/quality-heads-up/.
Das Tag funktioniert inline und als Block. Der Rumpf wird als Textblock unter einer Ueberschrift gerendert, die standardmaessig Note: lautet; die Inline-Form bekommt zusaetzlich einen senkrechten Balken links. Das erzeugte HTML traegt die CSS-Klasse block-note beziehungsweise inline-note.
Attribute stehen als name=value-Paare in Klammern vor dem Rumpf. Das Standard-Doclet kennt header, das die Ueberschrift aendert, kind, das als weitere CSS-Klasse ausgegeben wird, und id. Eine Notiz mit dem header Caution: erscheint damit unter diesem Wort statt unter Note:.
Zusaetzlich wird javadoc -tag erweitert, sodass sich das Tag aliasieren laesst: ein als warning:A:Warning: deklarierter Alias macht {@warning ...} zu einem @note mit eigener Ueberschrift.
Was das bedeutet
Hier holt die Auszeichnung nach, was grosse Codebasen laengst von Hand tun. Warnungen zu Sonderfaellen einer Methode stehen heute als gewoehnlicher Absatz, fett gesetzt oder in einer teameigenen Konvention, und kein Werkzeug kann sie von Fliesstext unterscheiden. Ein Tag gibt der Warnung einen Namen im erzeugten HTML, und das ist die Voraussetzung fuer alles Maschinelle: herausziehen, pruefen, ueber viele Repositories hinweg einheitlich darstellen.
Das interessante Detail ist kind, denn es wird zur CSS-Klasse, und an dieser Stelle wird aus einer Konvention eine Zusage. Wer sich auf ein kind wie thread-safety festlegt, bekommt etwas, das ein Skript findet; wer weiter fette Absaetze schreibt, nicht.
⚠️ Es handelt sich um einen Vorschlag im Rahmen von Quality Outreach, nicht um ein ausgeliefertes Feature: Das Programm existiert, damit FOSS-Projekte gegen fruehe Builds testen und Rueckmeldung geben, bevor ein Release feststeht. Als Weg fuer Feedback nennt der Beitrag das Ticket JDK-8363700 und die Mailingliste javadoc-dev.