CODEWITHSUNDEEP
javaandroidkotlinintegration-testingjavadoc
Dillon C
Dillon C

Reputation: 113

JavaDocs: How to Create a Custom Markup

I am creating a suite of instrumentation tests, written in Kotlin, that will hit numerous Web APIs. I plan to implement these tests into our CI/CD process. With that being said, I would like to add detailed documentation to each test for maintainability, verifying scenario coverage, etc.

Currently, I am using JavaDocs for documentation; however, there are only a handful of markups, most of which do not pertain to testing documentation (@return, @see, @author, @param, @exception, @sample, @simple, @since, @suppress, and @throws). As a result, I was wondering if there is a way to create custom markup and implement them into my documentation? For example, @scenario or @expected?

Upvotes: 3

Views: 1190

Answers (1)

Michael
Michael

Reputation: 44230

You need to use a custom doclet. See '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.

Upvotes: 2

Related Questions