JavaDocs：如何创建自定义标记

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

---

目前，我正在使用JavaDocs作为文档；然而，只有少数几个标记，其中大多数与测试文档无关（@return、@see、@author、@param、@exception、@sample、@simple、@begin、@suppress和@throws）。因此，我想知道是否有一种方法可以创建自定义标记并将其实现到我的文档中？例如，@scenario或@expected？

您需要使用自定义doclet。看

例如，假设您希望在中使用自定义标记，例如

@mytag

除了标准标签之外，您的文档注释如下

@param

和

@return

。要使用自定义文件中的信息 标记，您需要让doclet使用表示 您的自定义标签。最简单的方法之一就是使用 Doc的标记（字符串）方法或Doc的子类之一。这种方法 返回表示其名称为的任何标记的标记对象数组 匹配字符串参数。例如，如果方法是 那么是MethodDoc

method.tags("mytag")

将返回一个标记数组 表示方法文档中任何

@mytag

标记的对象 评论。然后，您可以使用访问

@mytag

标记中的信息 标记的文本方法。该方法返回一个表示 您可以根据需要解析或使用的标记的内容。例如 如果文档注释包含一个自定义标记，如 这：

然后text方法将返回 字符串“一些伪文本”。这里有一个独立的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());
                    }
                } 
            }
        }
    }
}

import com.sun.javadoc.*；
公共类列表标签{
公共静态布尔开始（RootDoc root）{
字符串标记名=“mytag”；
writeContents（root.classes（），标记名）；
返回true；
}
私有静态void writeContents（ClassDoc[]类，字符串标记名）{
for（int i=0；i0）{
如果（！classNamePrinted）{
System.out.println（“\n”+类[i].name（）+“\n”）；
classNamePrinted=true；
}
System.out.println（方法[j].name（））；
for（int k=0；k

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

---

它们不是注释。这只是JavaDoc的一个标记，而且两者的前缀都是@。您可以使用任何您想要的自定义标记，但是任何JavaDoc处理器都可能会忽略itI。我还认为一个好的测试应该是自文档化的。我个人认为你的计划没有多大价值。迈克尔，谢谢你的澄清。目前，我在文档中使用@scenario，JavaDoc处理器忽略了它。Michael，感谢您抽出时间提供一些有价值的见解。

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());
                    }
                } 
            }
        }
    }
}