DIY: Retrieving a Maven plugin's documentation


June 9, 2010 By Anders Hammar

One of the key things driving the adoption of Maven, is the rich set of plugins available. Whenever you want to add some functionality to the build process, or possibly even just want to do a one-time job, chances are that there is already a plugin for that.

When you want to use Maven plugins, you need to get more information about them to know how to use them. Most often, there is on-line documentation that describes the goals and parameters. However, sometimes no such documentation exists or you just cannot find it. Also, the on-line documentation very often describes the latest version of the plugin – what if you have to use an older version?

I recently faced a closed-source plugin, with no documentation. This blog post will explain the different options you have to retrieve information about a plugin, just by using Maven itself.

As mentioned above, the simplest way of viewing a plugin’s documentation is to use the one provided on-line. Normally in HTML and created by the Maven Site Plugin, this is what we have got used to with most open source plugins.

Not only does this documentation describe the available goals and its parameters, but it most often also provides examples and other useful information. If available, this should normally be your first choice. However, there are at least two other ways of retrieving information from a plugin about it’s goals and parameters. These come in handy when there is no other documentation, but also when you want to be sure to find the goals and parameters of a specific version of the plugin.

The first option, and most likely the easiest one to remember, is to use the help goal of the plugin itself. Here’s an example:

mvn compiler:help

This would give you an overview of the goals of the Maven Compiler Plugin. If you want more information, add the detail parameter:

mvn compiler:help –Ddetail

If you want to focus on a specific goal, you do that through the goal parameter:

mvn compiler:help –Ddetail –Dgoal=compile

Please note that this will describe the version of the plugin according to normal Maven plugin management. To override that, there is always the option of specify the plugin version through the standard Maven syntax.

mvn org.apache.maven.plugins:maven-compiler-plugin:2.3:help -Ddetail -Dgoal=compile

Another great thing about the help goal is that it is created by Maven Plugin Plugin. So you could very easy add this feature to your own plugin as well, only by adding a simple POM configuration.

However, this dependency is also the drawback. The functionality in Maven Plugin Plugin was added in version 2.4, so plugins (or older versions of plugins) written before that would not have the help goal. Fortunately, there is another option for those cases.

A fallback option is to use the Maven Help Plugin and its describe goal. It will work with any version of a plugin you want to describe. As an example, here is the equivalent to the one above:

mvn help:describe -Dplugin=org.apache.maven.plugins:maven-compiler-plugin:2.3 -Ddetail -Dmojo=compile

As this feature is described in detail in chapter 6.3.1 of Maven: The Complete Reference and also in the on-line documentation of Maven Help Plugin, I will not go into more details about it.

Try the different options and see which one you prefer. Please do note that even if they provide much the same info, there are some slight differences. In some areas, like information about default phase binding, I find the help:describe option more informative.