Java文档 : How to Create a Custom Markup

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'

Suppose, for example, that you want use a custom tag, say @mytag, in your documentation comments in addition to the standard tags like @param and @return. To make use of the information in your custom tags, you need to have your doclet use instances of Tag that represent your custom tags. One of the easiest ways to do that is to use the tags(String) method of Doc or one of Doc's subclasses. This method returns an array of Tag objects representing any tags whose name matches the string argument. For example, if method is an instance of MethodDoc, then

method.tags("mytag")

would return an array of Tag objects representing any @mytag tags in the method's documentation comment. You can then access the information in your @mytag tags with Tag's text method. That method returns a string representing the content of the tag which you can parse or use as needed. For example, if a documentation comment contained one of your custom tags like this:

@mytag Some dummy text.

then the text method would return the string "Some dummy text.". Here's a standalone doclet (not a subclass of the standard doclet) that uses these ideas to print out the text associated with all instances of a specified tag that it finds in method comments. It could be extended to find all instances of that tag in all comments.

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

The tag for which this doclet searches is specified by the variable tagName. The value of the tagName string can be any tag name, custom or standard. This doclet writes to standard out, but its output format could be modified, for example, to write HTML output to a file.