系统属性的JDK 12 Javadoc标记

JDK 12 Early Access Build 20 （ 2018/11/15 ）可用，可以用来试用新的Javadoc标签{@systemProperty} 。新的{@systemProperty} Javadoc标记在core-libs-dev邮件列表消息“ FYI：用于文档系统属性的新javadoc标记 ”中进行了讨论，并且是针对JDK-5076751 [“ javadocs中所需的系统属性文档”]引入的。。

{@systemPropery} Javadoc标记在其生成的输出中将其内容显示为普通文本，并使该内容可用于JDK 9引入的Javadoc搜索。该标签旨在用于记录应用程序的系统属性。

以下简单类将用于演示新的JDK 12 Javadoc标签{@systemProperty} ：

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 ，所以必须使用-private标志执行Javadoc工具，以为此字段生成文档。

下一个屏幕快照演示了使用JDK 12 Early Access Build 12 （不支持{@systemProperty}包含的javadoc命令行工具为简单类生成的文档。

Javadoc标签

上一个屏幕快照中的红色椭圆形表示{@systemProperty}标记在JDK的早期版本中未正确处理。该标记的内容不会显示，并且“搜索”功能与系统属性名称不匹配。

下一个屏幕快照展示了使用JDK 12 Early Access Build 20随附的命令行javadoc为同一类生成的文档。

Javadoc标签

上一个屏幕快照中的绿色椭圆形表示{@systemProperty}在OpenJDK JDK 12的Early Access Build 20中得到更好的支持。该标记的内容已正确显示在Javadoc本身中，并且搜索功能现在与系统属性名称匹配。

{@systemProperty}可能使开发人员更容易在Javadoc生成的文档中查找应用程序的系统属性的相关描述。前面的文章“ FYI：用于记录系统属性的新javadoc标记 ”讨论了可以利用此标记的其他Javadoc增强功能。可能的增强功能包括“列出所有系统属性的'摘要页面'”，添加“有关定义的'范围'的信息”以及允许“ {@systemProperty}标记中包含简短描述”，即“可以包含在搜索索引，AZ索引和摘要页面中。”

引入{@systemProperty}的Jonathan Gibbons FYI邮件列表消息还阐明了建议的用法：