Статьи

JDK 12 Javadoc Tag для системных свойств

Сентябрь 29, 2018

JDK 12 Early Access Build 20 ( 2018/11/15 ) доступен и может использоваться для опробования нового тега Javadoc {@systemProperty} . Новый {@systemProperty} Javadoc {@systemProperty} обсуждается в сообщении списка рассылки core-libs-dev « FYI: новый тег javadoc для документирования свойств системы » и вводится в ответ на JDK-5076751 [«Документация по свойствам системы, необходимая в javadocs»] ,

{@systemPropery} Javadoc {@systemPropery} отображает его содержимое в виде обычного текста в своем сгенерированном выводе и делает его доступным для поиска Javadoc, представленного в JDK 9 . Этот тег предназначен для документирования системных свойств приложения .

Следующий простой класс будет использован для демонстрации нового тега JDK 12 Javadoc {@systemProperty} :

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
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);
   }
}

Приведенный выше пример кода применяет {@systemProperty} к private атрибуту PROPERTY_NAME . Поскольку поле является private , инструмент Javadoc должен выполняться с флагом -private, чтобы документация была сгенерирована для этого поля.

На следующем снимке экрана демонстрируется документация, сгенерированная для простого класса с использованием инструмента командной строки javadoc включенного в JDK 12 Early Access Build 12 (который не поддерживал {@systemProperty} .

Тег Javadoc

Красные овалы в предыдущем снимке экрана показывают, что тег {@systemProperty} не обрабатывается должным образом в более ранних версиях JDK. Содержимое этого тега НЕ отображается, и функциональность «поиска» не совпадает с именем системного свойства.

На следующем снимке экрана демонстрируется документация, сгенерированная для этого же класса с использованием командной строки javadoc , поставляемой с JDK 12 Early Access Build 20 .

Тег Javadoc

Зеленые овалы на предыдущем снимке экрана показывают, что {@systemProperty} лучше поддерживается в раннем доступе к {@systemProperty} 20 OpenJDK JDK 12. Содержимое этого тега правильно отображается в самом Javadoc, и теперь возможность поиска соответствует имени системного свойства ,

Добавление {@systemProperty} потенциально облегчает разработчикам поиск соответствующих описаний системных свойств приложения среди сгенерированной Javadoc документации. В вышеупомянутом посте « FYI: новый тег Javadoc для свойств системы документа » обсуждаются другие усовершенствования Javadoc, которые могут быть сделаны для использования этого тега. Потенциальные улучшения включают в себя «сводную страницу», в которой перечислены все системные свойства », добавление« информации, касающейся «области действия» определения »и включение« краткого описания в тег {@systemProperty} », которое« может быть включен в индекс поиска, индекс AZ и страницу сводки ».

Сообщение со списком рассылки Jonathan Gibbons FYI, которое представляет {@systemProperty} также {@systemProperty} его рекомендуемое использование:

Где следует использовать тег? Тег должен использоваться в тексте определяющего экземпляра свойства. Здесь описываются характеристики системного свойства, которые могут включать в себя такую ​​информацию, как: «для чего это свойство», «как и когда оно устанавливается», «можно ли его изменить» и т. Д.

Добавление {@systemProperty} к инструменту Javadoc с JDK 12 Early Access Build 20 — незначительная вещь, но позволит разработчикам сделать документацию важных системных свойств более доступной для коллег-разработчиков.

Опубликовано на Java Code Geeks с разрешения Дастина Маркса, партнера нашей программы JCG . Смотрите оригинальную статью здесь: JDK 12 Javadoc Tag для свойств системы

Мнения, высказанные участниками Java Code Geeks, являются их собственными.

38
Share: