I doubt we regard this from different perspectives; it just seems we draw different conclusions from the information we find in our toolset. I like these types of discussion since they tend to clarify ideas. So ...
The meaning of @since
In my view "@since" indicates the version (or date) when some piece of functionality (even as small as a single parameter) was last changed, to assume its current behaviour. This includes the version/date when the functionality was first introduced into the tool. Neither a developer nor a user would have any interest in knowing that the functionality was first introduced in version 2.4 of the tool, but actually was refactored to work in a different way in version 2.7. The @since is not meant as some kind of archeological code history - we use the version control system for that; Mojo-doc and JavaDoc alike covers only a single revision and the @since permits us to tell the user "the behavior of this parameter was not changed in this release of the plugin", or vice versa.
Therefore, I liberally use the "@since" to indicate to my users that the behaviour of the jaxb2-maven-plugin may have changed - not that parameter XXX was introduced in revision A.B.C, since that information would be highly irrelevant for anybody (users in particular). This is very intentionally done, and - I feel - the correct way to indicate that users of the j-m-p version 2+ should verify that the plugin works as expected when they first include it into their builds.
Leveraging the users' toolset knowledge
The other of your statements ("we should rename parameters to make it clear to users that their behaviour has changed from an earlier version") holds merit if the Mojo/Plugin freely defines its API/configuration. This is, however, not the case with plugins that adapt an existing tool to the Maven build reactor.
The jaxb2-maven-plugin is that type of plugin (adapting SchemaGen and XJC) to Maven, and these JDK-provided tools expose a suite of options which most users already know. This implies that we should strive to as close to existing options as possible even if we move to a new major release with the j-m-p. In my case, I indicate the underlying parameter/option in the JavaDoc/MojoDoc, and include the corresponding documentation from the underlying tool, as indicated below:
/**
* <p>Corresponding SchemaGen parameter: {@code episode}.</p>
* <p>Generate an episode file from this XSD generation, so that other schemas
* that rely on this schema can be compiled later and rely on classes that are generated
* from this compilation. The generated episode file is really just a JAXB customization
* file (but with vendor extensions.)</p>
* <p>If this parameter is {@code true}, the episode file generated is
* called {@code META-INF/sun-jaxb.episode} and included in the artifact.</p>
*
* @see #STANDARD_EPISODE_FILENAME
* @since 2.0
*/
@Parameter(defaultValue = "true")
protected boolean generateEpisode;
Since this parameter was reimplemented in the 2.0 release of the plugin, I would indicate this by adding the "@since 2.0". We always strive for making behavior apparent to users, but I nevertheless inform them about the change to promote awareness.
|