[MPLUGIN-417] report and descriptor goal need to evaluate Javadoc comments differently

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 3.7.0
• Component/s: Plugin Plugin
• Assignee: Konrad Windszus
• Reporter: Konrad Windszus
• Created: 15/Aug/22 07:48
• Updated: 04/Sep/23 06:50
• Resolved: 18/Oct/22 10:26

Description

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

1. Still emits <a href= links
2. Does not resolve all javadoc tags
3. Does never emit a proper link for link javadoc taglets

 

The proposal is that

1. goal descriptor generates three different descriptor serializations (based on the same in-memory HTML descriptor):
   1. one with plain text according to https://maven.apache.org/ref/3.8.4/maven-plugin-api/plugin.html
   2. one with plain text and additional attributes for helpmojo
   3. another temporary one to be used from report containing HTML values 
2. goal helpmojo evaluates the deserialized descriptor from 2 at execution time of the resulting "help" mojo
3. goal report evaluates the deserialized enhanced descriptor from 3. 

Issue Links

• causes: MPLUGIN-428 Don't emit warning for missing javadoc URL of primitives
• causes: MPLUGIN-429 Don't emit warning for missing javadoc URI if no javadoc sources are configured
• is related to: MPLUGIN-443 Javadoc reference containing a link label with spaces are not detected
• is related to: MPLUGIN-444 JavadocLinkGenerator.createLink: Support nested binary class names
• is related to: MPLUGIN-298 The plugin descriptor generated by plugin:descriptor does not consider @see javadoc taglets
• is related to: MPLUGIN-9 Add link to javadoc in configuration description page for user defined types of Mojos.
• is related to: MJAVADOC-727 Make methods from JavadocUtil public which deal with retrieving "package-list"/"element-list"
• is related to: MPLUGIN-481 Provide improved plugin descriptor suitable for IDE integration
• is related to: MPLUGIN-433 Allow to reference aggregator javadoc from plugin report
• is related to: MPLUGIN-408 simplification in helpmojo build
• links to: GitHub Pull Request #139