[jira] [Commented] (MPLUGIN-417) report and descriptor goal need to evaluate Javadoc comments differently

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

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

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

kwin commented on code in PR #139:
URL: https://github.com/apache/maven-plugin-tools/pull/139#discussion_r996961032


##########
maven-script/maven-plugin-tools-beanshell/src/main/java/org/apache/maven/tools/plugin/extractor/beanshell/BeanshellMojoDescriptorExtractor.java:
##########
@@ -131,6 +131,7 @@ private MojoDescriptor createMojoDescriptor( String basedir, String resource, Pl
             throw new InvalidPluginDescriptorException( "Error scanning beanshell script", evalError );
         }
 
+        // FIXME: convert javadocs

Review Comment:
   I left the legacy handling in place, i.e. convert inline javadoc tags afterwards to HTML (but only for legacy extractors).





> report and descriptor goal need to evaluate Javadoc comments differently
> ------------------------------------------------------------------------
>
>                 Key: MPLUGIN-417
>                 URL: https://issues.apache.org/jira/browse/MPLUGIN-417
>             Project: Maven Plugin Tools
>          Issue Type: Improvement
>          Components: Plugin Plugin
>            Reporter: Konrad Windszus
>            Assignee: Konrad Windszus
>            Priority: Major
>
> Currently it is not explicitly specified in [https://maven.apache.org/ref/3.8.4/maven-plugin-api/plugin.html] which format the {{description}} field on plugin, mojo and parameter level should have.
> It partially contains HTML tags (also from converted inline javadoc taglets) which is problematic for [https://maven.apache.org/plugins/maven-help-plugin/describe-mojo.html] (which expects plain text).
> On the other hand, the same plugin descriptor is currently leveraged for goal {{report}} which should include all those HTML details from the source comment.
> Therefore both goals need to extract metadata from source files differently and {{report}} can no longer rely on the previously generated plugin descriptor file.
> In addition even the plain text descriptor should contain as many details as possible, i.e. it should be converted javadoc taglets -> html -> plain text to no loose any detail.
> Currently the plugin descriptor is written with {{{}GeneratorUtils.toText(){}}}at [https://github.com/apache/maven-plugin-tools/blob/706b1d0b6730d028350f18d8459eee8b123e2f67/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorGenerator.java#L186] which has the following flaws
>  # Still emits {{<a href=}} links
>  # Does not resolve all javadoc tags
>  # Does never emit a proper link for link javadoc taglets
>  
> The proposal is that
>  # goal {{descriptor}} generates three different descriptor serializations (based on the same in-memory HTML descriptor):
>  ## one with plain text according to [https://maven.apache.org/ref/3.8.4/maven-plugin-api/plugin.html]
>  ## one with plain text and additional attributes for {{helpmojo}}
>  ## another temporary one to be used from {{report}} containing HTML values 
>  # goal {{helpmojo}} evaluates the deserialized descriptor from 2 at execution time of the resulting "help" mojo
>  # goal {{report}} evaluates the deserialized enhanced descriptor from 3. 



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