issue 1708 : adding javadoc from xsd documentation tags and fixing...

...javadoc format to avoid erronous warnings / errors
eclipse-ee4j · Sep 4, 2023 · 5171895 · 5171895
1 parent c6cff6a
commit 5171895
Show file tree

Hide file tree

Showing 24 changed files with 167 additions and 116 deletions.
diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/BeanGenerator.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/BeanGenerator.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -697,7 +697,12 @@ private void generateEnumBody(EnumOutline eo) {
 
             // [RESULT]
             // public <valuetype> value() { return value; }
-            type.method(JMod.PUBLIC, baseExposedType, "value").body()._return($value);
+            {
+                JMethod m = type.method(JMod.PUBLIC, baseExposedType, "value");
+                m.javadoc().add(Messages.ENUM_VALUE_METHOD.toString());
+                m.javadoc().addReturn().add(Messages.ENUM_VALUE_METHOD_RETURN.toString());
+                m.body()._return($value);
+            }
 
             // [RESULT]
             // <constructor>(<valueType> v) {
@@ -739,6 +744,12 @@ private void generateEnumBody(EnumOutline eo) {
                 } else {
                     strForm = $v.invoke("toString");
                 }
+
+                m.javadoc().add(Messages.ENUM_FROM_VALUE_METHOD.toString());
+                m.javadoc().addParam($v).add(Messages.ENUM_FROM_VALUE_METHOD_PARAM.toString());
+                m.javadoc().addReturn().add(Messages.ENUM_FROM_VALUE_METHOD_RETURN.toString());
+                m.javadoc().addThrows(IllegalArgumentException.class).add(Messages.ENUM_FROM_VALUE_METHOD_THROW.toString());
+
                 m.body()._throw(ex.arg(strForm));
             }
         } else {

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/Messages.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/Messages.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -25,6 +25,12 @@ enum Messages {
     ILLEGAL_CONSTRUCTOR_PARAM, // 1 arg
     OBJECT_FACTORY_CONFLICT,    // 1 arg
     OBJECT_FACTORY_CONFLICT_RELATED,
+    ENUM_VALUE_METHOD, // 0 arg
+    ENUM_VALUE_METHOD_RETURN, // 0 arg
+    ENUM_FROM_VALUE_METHOD, // 0 arg
+    ENUM_FROM_VALUE_METHOD_PARAM, // 0 arg
+    ENUM_FROM_VALUE_METHOD_RETURN, // 0 arg
+    ENUM_FROM_VALUE_METHOD_THROW, // 0 arg
     ;
 
     private static final ResourceBundle rb = ResourceBundle.getBundle(Messages.class.getPackage().getName() + ".MessageBundle");

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/AbstractFieldWithVar.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/AbstractFieldWithVar.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -46,6 +46,10 @@ protected final void createField() {
         field = outline.implClass.field( JMod.PROTECTED,
             getFieldType(), prop.getName(false) );
 
+        if (prop.javadoc != null && prop.javadoc.length() > 0) {
+            field.javadoc().add(prop.javadoc);
+        }
+
         annotate(field);
     }
 

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/AbstractListField.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/AbstractListField.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -24,7 +24,9 @@
 import com.sun.codemodel.JPrimitiveType;
 import com.sun.codemodel.JType;
 import com.sun.tools.xjc.generator.bean.ClassOutlineImpl;
+import com.sun.tools.xjc.generator.bean.MethodWriter;
 import com.sun.tools.xjc.model.CPropertyInfo;
+import org.glassfish.jaxb.core.api.impl.NameConverter;
 
 /**
  * Common code for property renderer that generates a List as
@@ -96,6 +98,10 @@ protected final void generate() {
         if(eagerInstanciation)
             field.init(newCoreList());
 
+        if (prop.javadoc != null && prop.javadoc.length() > 0) {
+            field.javadoc().add(prop.javadoc);
+        }
+
         annotate(field);
 
         // generate the rest of accessors
@@ -141,7 +147,16 @@ private JExpression newCoreList() {
     /** Generates accessor methods. */
     protected abstract void generateAccessors();
 
-
+    protected void appendJavadoc(MethodWriter writer) {
+        String pname = NameConverter.standard.toVariableName(prop.getName(true));
+        List<Object> possibleTypes = listPossibleTypes(prop);
+        writer.javadoc().append(Messages.DEFAULT_GETTER_LIST_JAVADOC.format(pname, prop.getName(true)));
+        writer.javadoc().append(Messages.DEFAULT_GETTER_LIST_JAVADOC_TYPES.toString())
+                .append(possibleTypes)
+                .append(Messages.DEFAULT_GETTER_LIST_JAVADOC_TYPES_END.toString());
+        writer.javadoc().addReturn()
+                .append(Messages.DEFAULT_GETTER_LIST_RETURN.format(pname));
+    }
 
     /**
      * 

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/ArrayField.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/ArrayField.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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 +101,9 @@ public void generateAccessors() {
         //     return (retVal);
         // }
         $getAll = writer.declareMethod( exposedType.array(),"get"+prop.getName(true));
-        writer.javadoc().append(prop.javadoc);
+        if (prop.javadoc != null && prop.javadoc.length() > 0) {
+            writer.javadoc().append(prop.javadoc).append("\n\n");
+        }
         body = $getAll.body();
 
         body._if( acc.ref(true).eq(JExpr._null()) )._then()

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/ContentListField.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/ContentListField.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -100,34 +100,14 @@ public void generateAccessors() {
         //     return <ref>;
         // }
         $get = writer.declareMethod(listT,"get"+prop.getName(true));
-        writer.javadoc().append(prop.javadoc);
+        if (prop.javadoc != null && prop.javadoc.length() > 0) {
+            writer.javadoc().append(prop.javadoc).append("\n\n");
+        }
         JBlock block = $get.body();
         fixNullRef(block);  // avoid using an internal getter
         block._return(acc.ref(true));
 
-        String pname = NameConverter.standard.toVariableName(prop.getName(true));
-        writer.javadoc().append(
-            "Gets the value of the "+pname+" property.\n\n"+
-            "<p>\n" +
-            "This accessor method returns a reference to the live list,\n" +
-            "not a snapshot. Therefore any modification you make to the\n" +
-            "returned list will be present inside the Jakarta XML Binding object.\n" +
-            "This is why there is not a {@code set} method for the " +pname+ " property.\n" +
-            "\n"+
-            "<p>\n" +
-            "For example, to add a new item, do as follows:\n"+
-            "<pre>\n"+
-            "   get"+prop.getName(true)+"().add(newItem);\n"+
-            "</pre>\n"+
-            "\n\n"
-        );
-
-        writer.javadoc().append(
-            "<p>\n" +
-            "Objects of the following type(s) are allowed in the list\n")
-            .append(listPossibleTypes(prop));
-
-        writer.javadoc().addReturn().append("The value of the "+pname+" property.");
+        appendJavadoc(writer);
     }
 
     @Override

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/Messages.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/Messages.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -18,8 +18,13 @@
  * Message resources
  */
 public enum Messages {
-    DEFAULT_GETTER_JAVADOC,     // 1 arg
-    DEFAULT_SETTER_JAVADOC,     // 1 arg
+    DEFAULT_GETTER_JAVADOC,                 // 1 arg
+    DEFAULT_GETTER_RETURN,                  // 0 arg
+    DEFAULT_GETTER_LIST_RETURN,             // 1 arg
+    DEFAULT_SETTER_JAVADOC,                 // 1 arg
+    DEFAULT_GETTER_LIST_JAVADOC,            // 2 args
+    DEFAULT_GETTER_LIST_JAVADOC_TYPES,      // 0 arg
+    DEFAULT_GETTER_LIST_JAVADOC_TYPES_END,  // 0 arg
     ;
 
     private static final ResourceBundle rb = ResourceBundle.getBundle(Messages.class.getName().substring(0, Messages.class.getName().lastIndexOf('.'))+ ".MessageBundle");

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/NoExtendedContentField.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/NoExtendedContentField.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -103,34 +103,14 @@ public void generateAccessors() {
         //     return <ref>;
         // }
         $get = writer.declareMethod(listT,"get"+prop.getName(true));
-        writer.javadoc().append(prop.javadoc);
+        if (prop.javadoc != null && prop.javadoc.length() > 0) {
+            writer.javadoc().append(prop.javadoc).append("\n\n");
+        }
         JBlock block = $get.body();
         fixNullRef(block);  // avoid using an internal getter
         block._return(acc.ref(true));
 
-        String pname = NameConverter.standard.toVariableName(prop.getName(true));
-        writer.javadoc().append(
-            "Gets the value of the "+pname+" property.\n\n"+
-            "<p>\n" +
-            "This accessor method returns a reference to the live list,\n" +
-            "not a snapshot. Therefore any modification you make to the\n" +
-            "returned list will be present inside the Jakarta XML Binding object.\n" +
-            "This is why there is not a {@code set} method for the " +pname+ " property.\n" +
-            "\n"+
-            "<p>\n" +
-            "For example, to add a new item, do as follows:\n"+
-            "<pre>\n"+
-            "   get"+prop.getName(true)+"().add(newItem);\n"+
-            "</pre>\n"+
-            "\n\n"
-        );
-
-        writer.javadoc().append(
-            "<p>\n" +
-            "Objects of the following type(s) are allowed in the list\n")
-            .append(listPossibleTypes(prop));
-
-        writer.javadoc().addReturn().append("The value of the "+pname+" property.");
+        appendJavadoc(writer);
     }
 
     @Override

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/SingleField.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/SingleField.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -110,7 +110,7 @@ protected SingleField(ClassOutlineImpl context, CPropertyInfo prop, boolean forc
 
         List<Object> possibleTypes = listPossibleTypes(prop);
         writer.javadoc().addReturn()
-            .append("possible object is\n")
+            .append(Messages.DEFAULT_GETTER_RETURN.toString())
             .append(possibleTypes);
 
         // [RESULT]
@@ -133,6 +133,9 @@ protected SingleField(ClassOutlineImpl context, CPropertyInfo prop, boolean forc
         writer.javadoc().addParam($value)
             .append("allowed object is\n")
             .append(possibleTypes);
+        if (prop.javadoc != null && prop.javadoc.length() > 0) {
+            writer.javadoc().addXdoclet("see #" + $get.name() + "()");
+        }
     }
 
     @Override

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/UntypedListField.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/generator/bean/field/UntypedListField.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -98,34 +98,14 @@ public void generateAccessors() {
         //     return <ref>;
         // }
         $get = writer.declareMethod(listT,"get"+prop.getName(true));
-        writer.javadoc().append(prop.javadoc);
+        if (prop.javadoc != null && prop.javadoc.length() > 0) {
+            writer.javadoc().append(prop.javadoc).append("\n\n");
+        }
         JBlock block = $get.body();
         fixNullRef(block);  // avoid using an internal getter
         block._return(acc.ref(true));
 
-        String pname = NameConverter.standard.toVariableName(prop.getName(true));
-        writer.javadoc().append(
-            "Gets the value of the "+pname+" property.\n\n"+
-            "<p>\n" +
-            "This accessor method returns a reference to the live list,\n" +
-            "not a snapshot. Therefore any modification you make to the\n" +
-            "returned list will be present inside the Jakarta XML Binding object.\n" +
-            "This is why there is not a {@code set} method for the " +pname+ " property.\n" +
-            "\n"+
-            "<p>\n" +
-            "For example, to add a new item, do as follows:\n"+
-            "<pre>\n"+
-            "   get"+prop.getName(true)+"().add(newItem);\n"+
-            "</pre>\n"+
-            "\n\n"
-        );
-
-        writer.javadoc().append(
-            "<p>\n" +
-            "Objects of the following type(s) are allowed in the list\n")
-            .append(listPossibleTypes(prop));
-
-        writer.javadoc().addReturn().append("The value of the "+pname+" property.");
+        appendJavadoc(writer);
     }
 
     @Override

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/reader/xmlschema/BGMBuilder.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/reader/xmlschema/BGMBuilder.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -398,7 +398,7 @@ private BindInfo _getBindInfoReadOnly( XSComponent schemaComponent ) {
         BindInfo bi = externalBindInfos.get(schemaComponent);
         if(bi!=null)    return bi;
 
-        XSAnnotation annon = schemaComponent.getAnnotation();
+        XSAnnotation annon = _getXSAnnotation(schemaComponent);
         if(annon!=null) {
             bi = (BindInfo)annon.getAnnotation();
             if(bi!=null) {
@@ -411,6 +411,19 @@ private BindInfo _getBindInfoReadOnly( XSComponent schemaComponent ) {
         return null;
     }
 
+    private XSAnnotation _getXSAnnotation(XSComponent schemaComponent) {
+        XSAnnotation annon = schemaComponent.getAnnotation();
+        if (annon != null) {
+            return annon;
+        }
+        if (schemaComponent instanceof XSParticle) {
+            annon = ((XSParticle) schemaComponent).getTerm().getAnnotation();
+        } else if (schemaComponent instanceof XSAttributeUse) {
+            annon = ((XSAttributeUse) schemaComponent).getDecl().getAnnotation();
+        }
+        return annon;
+    }
+
     /**
      * A map that stores binding declarations augmented by XJC.
      */

diff --git a/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/reader/xmlschema/SimpleTypeBuilder.java b/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/reader/xmlschema/SimpleTypeBuilder.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates. 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
@@ -391,13 +391,17 @@ private TypeUse find( XSSimpleType type ) {
                 return CBuiltinLeafInfo.STRING.makeAdapted(SwaRefAdapterMarker.class,false);
         }
 
+        String documentation = "";
+        if (info.getDocumentation() != null && info.getDocumentation().length() > 0) {
+            documentation = info.getDocumentation().trim();
+        }
 
         // see if this type should be mapped to a type-safe enumeration by default.
         // if so, built a EnumXDucer from it and return it.
         if(type.isRestriction() && !noAutoEnum) {
             XSRestrictionSimpleType rst = type.asRestriction();
             if(shouldBeMappedToTypeSafeEnumByDefault(rst)) {
-                r = bindToTypeSafeEnum(rst,null,null, Collections.emptyMap(),
+                r = bindToTypeSafeEnum(rst,null, documentation, Collections.emptyMap(),
                             getEnumMemberMode(),null);
                 if(r!=null)
                     return r;
@@ -644,7 +648,7 @@ private List<CEnumConstant> buildCEnumConstants(XSRestrictionSimpleType type, bo
 
         for( XSFacet facet : type.getDeclaredFacets(XSFacet.FACET_ENUMERATION)) {
             String name=null;
-            String mdoc=builder.getBindInfo(facet).getDocumentation();
+            String mdoc=builder.getBindInfo(facet).getDocumentation().trim();
 
             if(!enums.add(facet.getValue().value))
                 continue;   // ignore the 2nd occasion