Details
-
Bug
-
Status: Closed
-
Minor
-
Resolution: Fixed
-
None
Description
It looks like currently if a parameter is missing a @since tag, the documentation for the plugin inherits the @since from the Mojo (relevant code seems to be here).
I assume the intention was to avoid having to repeat the @since tag for paramters which existed from the beginning. However, this can be quite confusing when developers forget to add the @since tag to parameters. In that case the documentation will claim an incorrect value.
An example for this can be seen in https://github.com/apache/maven-dependency-plugin/pull/241; the parameter was added in 3.2.0 but the author forgot to add the @since tag. Therefore the documentation erroneously claims the parameter exists since version 2.0 (when the Mojo was added).
Maybe it would be better to just leave the value blank and not inherit it from the Mojo. This way if the value is missing users can assume that the parameter is supported in the version they are using, but won't be that confused when the parameter is not supported yet. Whereas currently the documentation says the parameter should be supported and users start troubleshooting their build configuration until they notice that the documentation is incorrect and they just have to upgrade the plugin version.
Though this problem will likely become less relevant with MNG-7468.
Attachments
Issue Links
- links to