Retrieving a plugin's documentation


December 13, 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 online documentation that describes the goals and parameters. However, sometimes no such documentation exists or you just cannot find it. Also, the online documentation very often describes the latest version of the plugin – but what if you have to use an older version?

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 online. Not only does this documentation describe the available goals and the plugin’s 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, and 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 online 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 note that even if they provide much of the same information there are some slight differences. In some areas, like information about default phase binding, I find the help:describe option more informative.

  • http://twitter.com/bmathus Baptiste MATHUS

    There’s also a simple way to find documentation I often use with core maven plugins:
    1) open your preferred browser
    2) type “maven [thePluginYouWantHelpFor] plugin”
    3) type [enter]

    Most of the time, it will take you to the right maven generated website for the plugin. Sure, this is not as certain as the help plugin, but it can sometimes be quicker (particularly when you’re sure the website does exist, but you want to double-check one or more parameters).

    HTH.

    Baptiste