时间戳

首页 > 解决方案 > JavaDocs：如何创建自定义标记

java - JavaDocs：如何创建自定义标记

问题描述

我正在创建一套用 Kotlin 编写的仪器测试，它将影响许多 Web API。我计划将这些测试实施到我们的 CI/CD 流程中。话虽如此，我想为每个测试添加详细的文档，以实现可维护性、验证场景覆盖率等。

目前，我正在使用 JavaDocs 作为文档；但是，只有少数标记，其中大部分与测试文档无关（@return、@see、@author、@param、@exception、@sample、@simple、@since、@suppress 和 @throws ）。因此，我想知道是否有办法创建自定义标记并将它们实施到我的文档中？例如，@scenario 或@expected？

标签： javaandroidkotlinintegration-testingjavadoc

解决方案

您需要使用自定义 doclet。请参阅“创建和处理自定义标签”

例如，假设您想@mytag在文档注释中使用自定义标签，比如 @param和等标准标签@return。要使用自定义标签中的信息，您需要让 doclet 使用代表自定义标签的 Tag 实例。最简单的方法之一是使用 Doc 的 tags(String) 方法或 Doc 的子类之一。此方法返回一个 Tag 对象数组，表示名称与字符串参数匹配的任何标签。例如，如果 method 是 MethodDoc 的一个实例，那么

method.tags("mytag")

将返回一个 Tag 对象数组，表示@mytag方法文档注释中的任何标签。然后，您可以@mytag使用 Tag 的 text 方法访问标签中的信息。该方法返回一个表示标签内容的字符串，您可以根据需要对其进行解析或使用。例如，如果文档注释包含您的自定义标签之一，如下所示：

@mytag Some dummy text.

那么 text 方法将返回字符串“Some dummy text.”。这是一个独立的 doclet（不是标准 doclet 的子类），它使用这些想法打印出与它在方法注释中找到的指定标记的所有实例相关联的文本。它可以扩展为在所有评论中查找该标签的所有实例。

import com.sun.javadoc.*;

public class ListTags {
    public static boolean start(RootDoc root){ 
        String tagName = "mytag";
        writeContents(root.classes(), tagName);
        return true;
    }

    private static void writeContents(ClassDoc[] classes, String tagName) {
        for (int i=0; i < classes.length; i++) {
            boolean classNamePrinted = false;
            MethodDoc[] methods = classes[i].methods();
            for (int j=0; j < methods.length; j++) {
                Tag[] tags = methods[j].tags(tagName);
                if (tags.length > 0) {
                    if (!classNamePrinted) {
                        System.out.println("\n" + classes[i].name() + "\n");
                        classNamePrinted = true;
                    }
                    System.out.println(methods[j].name());
                    for (int k=0; k < tags.length; k++) {
                        System.out.println("   " + tags[k].name() + ": " 
                        + tags[k].text());
                    }
                } 
            }
        }
    }
}

此 doclet 搜索的标记由变量 tagName 指定。tagName 字符串的值可以是任何标签名称，自定义的或标准的。此 doclet 写入标准输出，但可以修改其输出格式，例如，将 HTML 输出写入文件。

推荐阅读