JavaDocs：如何创建自定义标记

Question

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

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

Answer 1

您需要使用自定义 doclet。见'Creating and handling custom tags'

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

method.tags("mytag")

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

@mytag Some dummy text.

那么文本方法将返回 字符串“一些虚拟文本。”。这是一个独立的 doclet（不是子类 的标准 doclet) 使用这些想法来打印出文本 与它在其中找到的指定标签的所有实例相关联 方法cmets。它可以扩展到查找所有实例 标记所有 cmets。

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 输出写入文件。