Question

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

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

  //...rest of the class here
}

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

输出可能如下所示，虽然只是将它放在那里会是一个开始！：

Foo - 示例参数

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

Answer 1

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

Answer 2

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

不要使用文字作为键，而是使用以PARAM _
在该常量上编写常规JavaDoc，而不是使用description参数。


/**
 * 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。

Answer 3

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

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

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

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

JavaDoc基于注释

3 个答案: