How to document runtime of a function with Javadoc

Question

I'm want to document the asymptotic runtime of a function, as it will be used for algorithm-engineering for graph problems. What's the most idiomatic way to do this? Is there a way to create new tags in Javadoc like @return or @author?

I provided an example below, which is the method to delete a vertex in the graph.

/**
 * Runtime: O( degreeOf(v) )    because every neighbour of [v] also needs to be updated.
 */
fun deleteVertex(v: V): SimpleGraph<V> {
    if (v in m.keys) {
        for (nb in m[v]!!)
            m[nb]!!.remove(v)
        m.remove(v)
    }

    return this
}

Answer 1

To create custom tags for Javadocs, simply follow these instructions.

You can create other customizations for Javadoc. For example, in Eclipse, you can create "templates" so that when you create new classes or add new methods, the IDE automatically apply this template to add a (Javadoc) comment formatted in the prescribed style of the template you applied. You can save these templates in an XML file so that you could share it with other members of your team. I am sure that IntelliJ and other modern IDEs will have similar features. I am just more familiarized with Eclipse. Here is a video I created many years ago on how to create a Code Formatter in Eclipse. If you advance to the 1:48 mark, you will see "Code Template" right above the "Code Formatter" option I selected in the video. Creating a code template is much easier than a formatter.

To do this, simply click on Windows > Preferences menu to get the Preferences popup. There, select Java > Code Style > Code Templates. in the right pane, expand Comments and select the component you wish to create a comment template for, for example Methods. Click Edit button and format the Javadoc comment to your liking. Obviously, you will have to do a bit of research to get really creative with your comments. For example, you might need to figure out how to use system variables or create your own. For example, in the image below, I made use the year variable to apply the current year whenever I create a new class.

Once you finish with all your template customizations, simply click the Export button and use the File Chooser dialog to save the file wherever you would like.

One last tip, if you need to embed code snippets in your Javadocs, you can follow the recommendations in this article. I do this very often. Sometimes I find it useful to embed a few lines of code to illustrate different use cases for the method. That way, other developers can see how to use the method in the correct context.