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 除了标准标记（例如， @param和@return。要利用您的自定义信息标签，您需要让doclet使用代表以下内容的Tag实例您的自定义标签。最简单的方法之一是使用 Doc或Doc的子类之一的tags（String）方法。这个方法返回Tag对象的数组，这些对象代表名称为的任何标签匹配字符串参数。例如，如果method是的实例然后是MethodDoc
method.tags("mytag")
将返回Tag数组表示方法文档中任何@mytag标签的对象评论。然后，您可以使用@mytag标签访问信息标记的文本方法。该方法返回一个字符串，表示您可以根据需要解析或使用的标签内容。例如，如果文档注释包含您的自定义标签之一，例如这个：
@mytag Some dummy text.
然后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输出写入文件。

JavaDocs：如何创建自定义标记

1 个答案: