[jira] [Commented] (MPLUGIN-420) Parameters documentation inheriting @since from Mojo can be confusing

["ASF GitHub Bot (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/MPLUGIN-420?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17615996#comment-17615996 ] 

ASF GitHub Bot commented on MPLUGIN-420:
----------------------------------------

slawekjaranowski opened a new pull request, #145:
URL: https://github.com/apache/maven-plugin-tools/pull/145

   - Parameters should have own since tag, we shouldn't copy this value from Mojo
   - remove unused parameters from private methods
   - use replace instead of replaceAll for simple replacement




> Parameters documentation inheriting @since from Mojo can be confusing
> ---------------------------------------------------------------------
>
>                 Key: MPLUGIN-420
>                 URL: https://issues.apache.org/jira/browse/MPLUGIN-420
>             Project: Maven Plugin Tools
>          Issue Type: Bug
>          Components: maven-plugin-tools-java
>            Reporter: Marcono1234
>            Assignee: Slawomir Jaranowski
>            Priority: Minor
>              Labels: up-for-grabs
>             Fix For: 3.7.0
>
>
> 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|https://github.com/apache/maven-plugin-tools/blob/2ee1d603e2a71bcd99d58a5e6a4c4b2d2669d9c4/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.java#L491-L504]).
> 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.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)