Uploaded image for project: 'Maven Plugin Tools'
  1. Maven Plugin Tools
  2. MPLUGIN-417

report and descriptor goal need to evaluate Javadoc comments differently

    XMLWordPrintableJSON

Details

    • Improvement
    • Status: Closed
    • Major
    • Resolution: Fixed
    • None
    • 3.7.0
    • Plugin Plugin
    • None

    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. 

      Attachments

        Issue Links

          Activity

            People

              kwin Konrad Windszus
              kwin Konrad Windszus
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: