Annotations vs. Javadoc in Maven Mojos

I’am somehow confused about annotating fields in my maven mojo. E.g. for retrieving the MavenProject instance the code would look like this

/**
 * @property property="${project}"
 * @readonly
 * @required
 */
private MavenProject project;

or it could look like this (does the same)

@Parameter(defaultValue = "${project}", readonly = true, required = true)
private MavenProject project;

You can even combine both variants, which also works somehow.

  1. What exactly is the difference between those variants?
  2. Is one of the methods deprecated / outdated? What is the preferred way?
  3. Variant “javadoc”: What is the point in encoding program logic into a comment?

The Javadoc variant is the old method for specifying the information that should go into plugin.xml descriptor. Java Annotations were only introduced in Java 5.

The Proposal for Java 5 Annotations for MOJOs describes some of the advantages of using annotations over Javadoc tags:

Using java 5 annotations instead of javadoc ones have multiple benefits:

  • compile-time checks for plugin metadata, with enums for some annotations
  • inheritance support
  • annotations are supported in most IDEs, providing code-completion and syntactic checks

Additionally, the maven-plugin-plugin documentation mentions that it allows to have MOJO super classes in different projects and their source code does not need to be available.

Which method to use?

I would use Java 5 annotations for the reasons named above and also because of the point you make in your third question: program logic should not be encoded in a comment.