Java >> Java Tutorial >  >> JDK

JDK 12 Javadoc-Tag für Systemeigenschaften

JDK

JDK 12 Early Access Build 20 (15.11.2018 ) ist verfügbar und kann verwendet werden, um das neue Javadoc-Tag {@systemProperty} auszuprobieren . Die neue {@systemProperty} Das Javadoc-Tag wird in der core-libs-dev-Mailinglistennachricht „FYI:new javadoc tag to document system properties“ besprochen und wurde als Antwort auf JDK-5076751 [„System Properties Documentation Needed in Javadocs“] eingeführt.

Die {@systemPropery} Das Javadoc-Tag zeigt seinen Inhalt als normalen Text in seiner generierten Ausgabe an und stellt den Inhalt für die mit JDK 9 eingeführte Javadoc-Suche zur Verfügung. Dieses Tag soll zum Dokumentieren der Systemeigenschaften einer Anwendung verwendet werden.

Die folgende einfache Klasse wird verwendet, um das neue JDK 12 Javadoc-Tag {@systemProperty} zu demonstrieren :

package dustin.examples.jdk12.properties;

import static java.lang.System.out;

/**
 * Class with sole purpose to illustrate JDK 12's
 * support for {@literal {@systemProperty}}.
 */
public class PropertiesDemo
{
   /**
    * {@systemProperty blog.title} can be specified to
    * provide a blog title.
    */
   private final static String PROPERTY_NAME = "blog.title";

   public static void main(final String[] arguments)
   {
      final String property = System.getProperty(PROPERTY_NAME);
      out.println("Property " + PROPERTY_NAME + ": " + property);
   }
}

Das obige Codebeispiel gilt für {@systemProperty} zum private Attribut PROPERTY_NAME . Weil das Feld private ist , muss das Javadoc-Tool mit dem Flag -private ausgeführt werden, damit die Dokumentation für dieses Feld generiert wird.

Der nächste Screenshot zeigt die Dokumentation, die für die einfache Klasse mit javadoc generiert wurde Befehlszeilentool, das in JDK 12 Early Access Build 12 enthalten ist (der keine Unterstützung für {@systemProperty} hatte .

Die roten Ovale im vorherigen Screenshot zeigen, dass die {@systemProperty} -Tag wird in früheren Versionen des JDK nicht ordnungsgemäß verarbeitet. Der Inhalt dieses Tags wird NICHT angezeigt und die „Suchfunktion“ stimmt nicht mit dem Systemeigenschaftsnamen überein.

Der nächste Screenshot zeigt die Dokumentation, die für dieselbe Klasse mit der Befehlszeile javadoc generiert wurde das mit JDK 12 Early Access Build 20 geliefert wird .

Die grünen Ovale im vorherigen Screenshot zeigen diese {@systemProperty} wird in Early Access Build 20 von OpenJDK JDK 12 besser unterstützt. Der Inhalt dieses Tags wird im Javadoc selbst korrekt angezeigt und die Suchfunktion stimmt jetzt mit dem Systemeigenschaftsnamen überein.

Die Hinzufügung von {@systemProperty} macht es möglicherweise Entwicklern leichter, relevante Beschreibungen von Systemeigenschaften für eine Anwendung in der von Javadoc generierten Dokumentation zu finden. Der oben erwähnte Beitrag „FYI:new javadoc tag to document system properties“ diskutiert andere Javadoc-Verbesserungen, die möglicherweise vorgenommen werden könnten, um dieses Tag zu nutzen. Zu den potenziellen Verbesserungen gehören „eine ‚Zusammenfassungsseite‘, die alle Systemeigenschaften auflistet“, das Hinzufügen von „Informationen zum ‚Umfang‘ der Definition“ und die Möglichkeit, „eine kurze Beschreibung in den {@systemProperty} aufzunehmen Tag“, das „in den Suchindex, den A-Z-Index und die Übersichtsseite aufgenommen werden könnte“.

Die Jonathan Gibbons FYI-Mailinglistennachricht, die {@systemProperty} einführt buchstabiert auch seine empfohlene Verwendung:

Wo soll das Tag verwendet werden? Das Tag sollte im Text der definierenden Instanz der Eigenschaft verwendet werden. Hier werden die Merkmale der Systemeigenschaft beschrieben, die Informationen enthalten können wie:„Wozu dient die Eigenschaft“, „Wie und wann wird sie festgelegt“, „Kann sie geändert werden“ usw.

Die Hinzufügung von {@systemProperty} zum Javadoc-Tool mit JDK 12 Early Access Build 20 ist eine Kleinigkeit, wird es Entwicklern aber ermöglichen, die Dokumentation wichtiger Systemeigenschaften für andere Entwickler leichter zugänglich zu machen.

Java-Tag