[MPLUGIN-535] maven-plugin-plugin clobbers code block formatting

• Type: Bug
• Status: Open
• Priority: Minor
• Resolution: Unresolved
• Component/s: Plugin Plugin
• Assignee: Unassigned
• Reporter: Ashley Scopes
• Created: 14/Sep/24 10:47
• Updated: 14/Sep/24 10:47

Description

If a plugin parameter JavaDoc provides a code example within a <pre/> HTML tag, then it appears that the generated Help Mojo discards this information and renders the content inline, discarding whitespace detail. This results in examples being incorrectly formatted in the help goal.

ewer versions of Java introduce a snippet doclet that can replace this but this is not available within Java 11 releases of JavaDoc, so <pre/> needs to be respected as well.

Example output:

[INFO]       For example:
[INFO]       <binaryUrlPlugins> <!-- FTP resource --> <binaryUrlPlugin>
[INFO]       <url>ftp://myorganisation.org/protoc/plugins/myplugin.exe</url>
[INFO]       </binaryUrlPlugin> <!-- HTTP resource with custom options-->
[INFO]       <binaryUrlPlugin>
[INFO]       <url>https://myorganisation.org/protoc/plugins/myplugin2.exe</url>
[INFO]       <options>foo=bar,baz=bork</options> </binaryUrlPlugin> <!-- HTTP resource
[INFO]       that is a ZIP holding the binary we want. --> <binaryUrlPlugin>
[INFO]       <url>jar:https://myorganisation.org/protoc/plugins/myplugin3.zip!/protoc-gen-something.exe</url>
[INFO]       </binaryUrlPlugin> </binaryUrlPlugins>
[INFO]       Objects support the following attributes:

Produced from the following JavaDoc comment (which renders with correct formatting if using JavaDoc itself):

  /**
   * Binary plugins to use with the protobuf compiler, specified as a valid URL.
   *
   * <p>This includes support for:
   *
   * <ul>
   *   <li>Local file system objects, specified using {@code file://path/to/file}</li>
   *   <li>HTTP resources, specified using {@code http://example.website/path/to/file}</li>
   *   <li>HTTPS resources, specified using {@code https://example.website/path/to/file}</li>
   *   <li>FTP resources, specified using {@code ftp://example.server/path/to/file}</li>
   * </ul>
   *
   * <p>Additionally, the {@code jar} protocol can be used with any of the above to
   * enable extracting a file from a JAR or ZIP and using it directly.
   *
   * <p>For example:
   * <pre>{@code
   * <binaryUrlPlugins>
   *   <!-- FTP resource -->
   *   <binaryUrlPlugin>
   *     <url>ftp://myorganisation.org/protoc/plugins/myplugin.exe</url>
   *   </binaryUrlPlugin>
   *
   *   <!-- HTTP resource with custom options-->
   *   <binaryUrlPlugin>
   *     <url>https://myorganisation.org/protoc/plugins/myplugin2.exe</url>
   *     <options>foo=bar,baz=bork</options>
   *   </binaryUrlPlugin>
   *
   *   <!-- HTTP resource that is a ZIP holding the binary we want. -->
   *   <binaryUrlPlugin>
   *     <url>jar:https://myorganisation.org/protoc/plugins/myplugin3.zip!/protoc-gen-something.exe</url>
   *   </binaryUrlPlugin>
   * </binaryUrlPlugins>
   * }</pre>
   *
   * <p>Objects support the following attributes:
   *
   * <ul>
   *   <li>{@code url} - the URL to resolve.</li>
   *   <li>{@code options} - a string of options to pass to the plugin
   *       - optional.</li>
   *   <li>{@code order} - an integer order to run the plugins in. Defaults
   *       to 100,000. Higher numbers run later than lower numbers.</li>
   *   <li>{@code skip} - set to {@code true} to skip invoking this plugin -
   *       useful if you want to control whether the plugin runs via a
   *       property - optional.</li>
   * </ul>
   *
   * @since 2.0.0
   */
  @Parameter
  @Nullable List<UrlProtocPluginBean> binaryUrlPlugins;

See https://github.com/ascopes/protobuf-maven-plugin/blob/main/protobuf-maven-plugin/src/main/java/io/github/ascopes/protobufmavenplugin/mojo/AbstractGenerateMojo.java#L232 for a reproduction.