[#1826] XJC should preserve some XML entities in generated JavaDoc

Author: laurentschoelens

jaxb-ri/codemodel/codemodel/src/main/java/com/sun/codemodel/JCommentPart.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -10,9 +11,11 @@
 
 package com.sun.codemodel;
 
+import java.util.AbstractMap;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Iterator;
+import java.util.List;
 
 /**
  * A part is a part of a javadoc comment, and it is a list of values.
@@ -31,6 +34,13 @@
 public class JCommentPart extends ArrayList<Object> {
 
     private static final long serialVersionUID = 1L;
+    private static final List<AbstractMap.SimpleImmutableEntry<String, String>> ESCAPED_XML_JAVADOC = new ArrayList<>();
+    static {
+        ESCAPED_XML_JAVADOC.add(new AbstractMap.SimpleImmutableEntry<>("&", "&amp;"));
+        ESCAPED_XML_JAVADOC.add(new AbstractMap.SimpleImmutableEntry<>("<", "&lt;"));
+        ESCAPED_XML_JAVADOC.add(new AbstractMap.SimpleImmutableEntry<>(">", "&gt;"));
+        ESCAPED_XML_JAVADOC.add(new AbstractMap.SimpleImmutableEntry<>("@", "&#064;"));
+    }
 
     protected JCommentPart() {
     }
@@ -46,7 +56,18 @@ public JCommentPart append(Object o) {
         return this;
     }
 
-        @Override
+    /**
+     * Appends a new value with escaped XML.
+     *
+     * If the value is {@link JType} it will be printed as a @link tag.
+     * Otherwise it will be converted to String via {@link Object#toString()}.
+     */
+    public JCommentPart appendXML(String s) {
+        add(escapeXML(s));
+        return this;
+    }
+
+    @Override
     public boolean add(Object o) {
         flattenAppend(o);
         return true;
@@ -112,6 +133,29 @@ protected void format( JFormatter f, String indent ) {
             f.nl();
     }
 
+    /**
+     * Escapes the XML tags for Javadoc compatibility
+     */
+    private String escapeXML(String s) {
+        if (s == null) {
+            return s;
+        }
+        for (AbstractMap.SimpleImmutableEntry<String, String> entry : ESCAPED_XML_JAVADOC) {
+            int entryKeyLength = entry.getKey().length();
+            int entryValueLength = entry.getValue().length();
+            int idx = -1;
+            while (true) {
+                idx = s.indexOf(entry.getKey(), idx);
+                if (idx < 0) {
+                    break;
+                }
+                s = s.substring(0, idx) + entry.getValue() + s.substring(idx + entryKeyLength);
+                idx += entryValueLength;
+            }
+        }
+        return s;
+    }
+
     /**
      * Escapes the appearance of the comment terminator.
      */

jaxb-ri/codemodel/codemodel/src/main/java/com/sun/codemodel/JDocComment.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -54,12 +55,18 @@ public JDocComment(JCodeModel owner) {
         this.owner = owner;
     }
 
-        @Override
+    @Override
     public JDocComment append(Object o) {
         add(o);
         return this;
     }
 
+    @Override
+    public JDocComment appendXML(String s) {
+        super.appendXML(s);
+        return this;
+    }
+
     /**
      * Append a text to a @param tag to the javadoc
      */

jaxb-ri/codemodel/codemodel/src/test/java/com/sun/codemodel/tests/JCommentTest.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2021, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -44,4 +45,28 @@ public void testJavadoc() throws Throwable {
         assertTrue(generatedClass.contains("</p>"));
         assertFalse(generatedClass.contains("&"));
     }
+
+    /**
+     * This should produce the following javadoc :<br><br>
+     * Age &lt;&gt; 18 &amp; age &lt;&gt; 21 &#064;home
+     */
+    public void testJavadocXML() throws Throwable {
+        JCodeModel model = new JCodeModel();
+        String className = "gh1826.JavadocTest";
+        JDefinedClass cls = model._class(className, ClassType.CLASS);
+        JDocComment comment = cls.javadoc();
+        comment.appendXML("Age <> 18 & age <> 21 @home");
+
+        ByteArrayOutputStream os = new ByteArrayOutputStream();
+        OutputStreamCodeWriter fileCodeWriter = new OutputStreamCodeWriter(os, "UTF-8");
+        model.build(fileCodeWriter);
+
+        String generatedClass = os.toString(StandardCharsets.UTF_8);
+        System.out.println(generatedClass);
+        assertFalse(generatedClass.contains("<"));
+        assertFalse(generatedClass.contains(">"));
+        assertFalse(generatedClass.contains("@"));
+        assertTrue(generatedClass.contains("&amp;"));
+        assertTrue(generatedClass.contains("&#064;"));
+    }
 }

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/BeanGenerator.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -556,7 +557,7 @@ private void generateClassBody(ClassOutlineImpl cc) {
         }
 
         // generate some class level javadoc
-        cc.ref.javadoc().append(target.javadoc);
+        cc.ref.javadoc().appendXML(target.javadoc);
 
         cc._package().objectFactoryGenerator().populate(cc);
     }
@@ -615,7 +616,7 @@ private EnumOutline generateEnumDef(CEnumLeafInfo e) {
 
         type = getClassFactory().createClass(
                 getContainer(e.parent, EXPOSED), e.shortName, e.getLocator(), ClassType.ENUM);
-        type.javadoc().append(e.javadoc);
+        type.javadoc().appendXML(e.javadoc);
 
         return new EnumOutline(e, type) {
 
@@ -682,7 +683,7 @@ private void generateEnumBody(EnumOutline eo) {
 
             // set javadoc
             if (mem.javadoc != null) {
-                constRef.javadoc().append(mem.javadoc);
+                constRef.javadoc().appendXML(mem.javadoc);
             }
 
             eo.constants.add(new EnumConstantOutline(mem, constRef) {

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/AbstractFieldWithVar.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -47,7 +48,7 @@ protected final void createField() {
             getFieldType(), prop.getName(false) );
 
         if (prop.javadoc != null && prop.javadoc.length() > 0) {
-            field.javadoc().add(prop.javadoc);
+            field.javadoc().appendXML(prop.javadoc);
         }
 
         annotate(field);

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/AbstractListField.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -99,7 +100,7 @@ protected final void generate() {
             field.init(newCoreList());
 
         if (prop.javadoc != null && prop.javadoc.length() > 0) {
-            field.javadoc().add(prop.javadoc);
+            field.javadoc().appendXML(prop.javadoc);
         }
 
         annotate(field);

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/ArrayField.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -102,7 +103,7 @@ public void generateAccessors() {
         // }
         $getAll = writer.declareMethod( exposedType.array(),"get"+prop.getName(true));
         if (prop.javadoc != null && prop.javadoc.length() > 0) {
-            writer.javadoc().append(prop.javadoc).append("\n\n");
+            writer.javadoc().appendXML(prop.javadoc).append("\n\n");
         }
         body = $getAll.body();
 
@@ -129,7 +130,7 @@ public void generateAccessors() {
         $get.body()._if(acc.ref(true).eq(JExpr._null()))._then()
             ._throw(JExpr._new(codeModel.ref(IndexOutOfBoundsException.class)));
 
-        writer.javadoc().append(prop.javadoc);
+        writer.javadoc().appendXML(prop.javadoc);
         $get.body()._return(acc.ref(true).component($idx));
 
         writer.javadoc().addReturn().append("one of\n").append(returnTypes);
@@ -156,7 +157,7 @@ public void generateAccessors() {
             codeModel.VOID,
             "set"+prop.getName(true));
 
-        writer.javadoc().append(prop.javadoc);
+        writer.javadoc().appendXML(prop.javadoc);
         $value = writer.addParameter(exposedType.array(),"values");
 
         $setAll.body()._if( $value.eq(JExpr._null()) )._then()
@@ -189,7 +190,7 @@ public void generateAccessors() {
         $idx = writer.addParameter( codeModel.INT, "idx" );
         $value = writer.addParameter( exposedType, "value" );
 
-        writer.javadoc().append(prop.javadoc);
+        writer.javadoc().appendXML(prop.javadoc);
 
         body = $set.body();
         body._return( JExpr.assign(acc.ref(true).component($idx),

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/ConstField.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2024 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -57,7 +58,7 @@ final class ConstField extends AbstractField {
 
         // Do not append empty javadoc.
         if ( (prop.javadoc != null) && (prop.javadoc.length() > 0) )
-            $ref.javadoc().append(prop.javadoc);
+            $ref.javadoc().appendXML(prop.javadoc);
 
         annotate($ref);
     }

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/ContentListField.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -101,7 +102,7 @@ public void generateAccessors() {
         // }
         $get = writer.declareMethod(listT,"get"+prop.getName(true));
         if (prop.javadoc != null && prop.javadoc.length() > 0) {
-            writer.javadoc().append(prop.javadoc).append("\n\n");
+            writer.javadoc().appendXML(prop.javadoc).append("\n\n");
         }
         JBlock block = $get.body();
         fixNullRef(block);  // avoid using an internal getter

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/NoExtendedContentField.java

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Distribution License v. 1.0, which is available at
@@ -104,7 +105,7 @@ public void generateAccessors() {
         // }
         $get = writer.declareMethod(listT,"get"+prop.getName(true));
         if (prop.javadoc != null && prop.javadoc.length() > 0) {
-            writer.javadoc().append(prop.javadoc).append("\n\n");
+            writer.javadoc().appendXML(prop.javadoc).append("\n\n");
         }
         JBlock block = $get.body();
         fixNullRef(block);  // avoid using an internal getter