基于注解的JavaDoc答案

【问题标题】：JavaDoc based on annotations基于注解的JavaDoc
【发布时间】：2015-04-17 06:32:59
【问题描述】：

我有一个包含类级变量注释的类。在我的具体情况下，它是表示配置参数的 uimaFIT 注释，但为了简单起见，我们假设如下：

public class MyClass{
  @MyParameter(key="Foo", description="Example parameter")
  private String myVariable;

  //...rest of the class here
}

在我的 JavaDoc 中，我希望能够提取标有 @MyParameter 的变量，并在类页面上列出键和描述。（原因是这些参数的值可以由用户注入，鉴于我已经在注释中为它们写了描述，单独写文档似乎没有意义。）

输出可能如下所示，尽管只是将其放入其中只是一个开始！：

Foo - 示例参数

这可能吗？如果需要，我不介意编写自己的类来“扩展”JavaDoc，但可以让有人指出我正确的方向！

【问题讨论】：

标签： java annotations javadoc uima

【解决方案1】：

我相信您正在寻找 doclets https://docs.oracle.com/javase/6/docs/technotes/guides/javadoc/doclet/overview.html 它们允许您扩展 JavaDoc 功能。您可以编写自己的 doclet 并使用反射 api 来收集您的注释数据。

【讨论】：

【解决方案2】：

uimaFIT 对此有一个解决方案。 uimaFIT 可以从 JavaDoc 中提取信息并将其放入其描述中，而不是从 uimaFIT 注释中提取信息并将其放入 JavaDoc。所以这就是你要做的：

不要对键使用文字，而是使用以 PARAM_ 开头的常量
在该常量上编写常规 JavaDoc，而不是使用描述参数。


/**
 * Enable or disable my feature.
 */
public static final String PARAM_ENABLE_FEATURE = "enableFeature";
@ConfigurationParameter(name=PARAM_ENABLE_FEATURE)
private boolean enableFeature;

现在，使用 uimafit-maven-plugin 从 JavaDoc 中自动填写描述：

<plugins>
    <plugin>
        <groupId>org.apache.uima</groupId>
        <artifactId>uimafit-maven-plugin</artifactId>
        <version>2.1.0</version>
        <executions>
            <execution>
                <id>default</id>
                <phase>process-classes</phase>
                <goals>
                    <goal>enhance</goal>
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

更多信息请参考uimaFIT documentation。

披露：我正在研究 uimaFIT。

【讨论】：

【解决方案3】：

Javadoc .html 文件由javadoc 工具创建。可以插入doclets自定义javadoc的输出。

如果您需要编写自己的 Javadoc 插件，最好从现有代码开始，而不是从头开始。

一个读取注解并将结果添加到 Javadoc 输出的 Javadoc 插件用于 plume-lib 的 Options 注解。如果程序使用@Option 注释，则其Javadoc 包含对其命令行选项的描述。这里是two examples。优点是您只需编写一次文档；源代码、手册和使用信息始终保持同步。

您可以在plume-lib repository 中找到OptionsDoclet source code。您将需要对其进行自定义以生成所需表单的输出。

【讨论】：