Parse javadoc tags in xdoc generator (only @SInCE is supported atm) (#…

…414)
codehaus-plexus · Feb 17, 2024 · 1ca6d58 · 1ca6d58
1 parent 9a4a130
commit 1ca6d58
Show file tree

Hide file tree

Showing 5 changed files with 45 additions and 13 deletions.
diff --git a/modello-plugins/modello-plugin-xdoc/pom.xml b/modello-plugins/modello-plugin-xdoc/pom.xml
@@ -30,6 +30,11 @@
       <artifactId>jsoup</artifactId>
       <version>1.17.2</version>
     </dependency>
+    <dependency>
+      <groupId>com.github.chhorz</groupId>
+      <artifactId>javadoc-parser</artifactId>
+      <version>0.3.1</version>
+    </dependency>
     <dependency>
       <groupId>org.xmlunit</groupId>
       <artifactId>xmlunit-core</artifactId>

diff --git a/...ins/modello-plugin-xdoc/src/main/java/org/codehaus/modello/plugin/xdoc/XdocGenerator.java b/...ins/modello-plugin-xdoc/src/main/java/org/codehaus/modello/plugin/xdoc/XdocGenerator.java
@@ -28,14 +28,14 @@
 import java.io.File;
 import java.io.IOException;
 import java.io.Writer;
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.List;
-import java.util.Map;
-import java.util.Properties;
-import java.util.Set;
-import java.util.Stack;
-
+import java.util.*;
+import java.util.stream.Collectors;
+
+import com.github.chhorz.javadoc.JavaDoc;
+import com.github.chhorz.javadoc.JavaDocParserBuilder;
+import com.github.chhorz.javadoc.OutputType;
+import com.github.chhorz.javadoc.tags.BlockTag;
+import com.github.chhorz.javadoc.tags.SinceTag;
 import org.codehaus.modello.ModelloException;
 import org.codehaus.modello.ModelloParameterConstants;
 import org.codehaus.modello.ModelloRuntimeException;
@@ -688,8 +688,24 @@ private static void writeMarkupElement(XMLWriter w, String name, String markup)
      * @return valid XML string
      */
     private static String rewrite(String text) {
-        Document document = Jsoup.parseBodyFragment(text);
+        JavaDoc javaDoc = JavaDocParserBuilder.withStandardJavadocTags()
+                .withOutputType(OutputType.HTML)
+                .build()
+                .parse(text);
+        String html = javaDoc.getDescription()
+                + javaDoc.getTags().stream()
+                        .map(XdocGenerator::renderJavaDocTag)
+                        .filter(Objects::nonNull)
+                        .collect(Collectors.joining("\n", "\n", ""));
+        Document document = Jsoup.parseBodyFragment(html);
         document.outputSettings().syntax(Document.OutputSettings.Syntax.xml);
         return document.body().html();
     }
+
+    private static String renderJavaDocTag(BlockTag tag) {
+        if (tag instanceof SinceTag) {
+            return "<p><b>Since</b>: " + ((SinceTag) tag).getSinceText() + "</p>";
+        }
+        return null;
+    }
 }
diff --git a/...modello-plugin-xdoc/src/test/java/org/codehaus/modello/plugin/xdoc/XdocGeneratorTest.java b/...modello-plugin-xdoc/src/test/java/org/codehaus/modello/plugin/xdoc/XdocGeneratorTest.java
@@ -23,6 +23,7 @@
  */
 
 import java.io.File;
+import java.nio.file.Files;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Properties;
@@ -77,7 +78,10 @@ public void testHtmlToXml() throws Exception {
                 .withTest(Input.fromFile(new File(getOutputDirectory(), "html4.xml")))
                 .build();
 
-        assertFalse(diff.toString(), diff.hasDifferences());
+        assertFalse(
+                diff.toString() + "\nGenerated output:\n"
+                        + new String(Files.readAllBytes(new File(getOutputDirectory(), "html4.xml").toPath())),
+                diff.hasDifferences());
     }
 
     private void checkMavenXdocGenerator() throws Exception {

diff --git a/modello-plugins/modello-plugin-xdoc/src/test/resources/html4.expected.xml b/modello-plugins/modello-plugin-xdoc/src/test/resources/html4.expected.xml
@@ -17,8 +17,12 @@
 </source>
       <a name="class_model"/>
       <subsection name="model">
-        <p>This is a description in HTML4
-<br /><strong>NOTE: </strong> HTML linebreak should be converted to selfclosing XML-tag</p>
+        <p>Whether this proxy configuration is the active one. Note: While the type of this field is <code>String</code> for technical reasons, the semantic type is actually <code>boolean</code>.
+<br />
+ This is a description in HTML4
+<br /><strong>NOTE: </strong> HTML linebreak should be converted to selfclosing XML-tag
+<br />
+<p><b>Since</b>: Maven 3</p></p>
         <table>
           <tr>
             <th>Element</th>

diff --git a/modello-plugins/modello-plugin-xdoc/src/test/resources/html4.mdo b/modello-plugins/modello-plugin-xdoc/src/test/resources/html4.mdo
@@ -16,8 +16,11 @@
       <comment>This is a comment</comment>
       <description>
         <![CDATA[
+            Whether this proxy configuration is the active one. Note: While the type of this field
+            is {@code String} for technical reasons, the semantic type is actually {@code boolean}.<br>
             This is a description in HTML4<br>
-            <strong>NOTE: </strong> HTML linebreak should be converted to selfclosing XML-tag
+            <strong>NOTE: </strong> HTML linebreak should be converted to selfclosing XML-tag<br>
+            @since Maven 3
           ]]>
       </description>
       <name>Model</name>