eclipse-ee4j#1117: xjc-generated classes may have methods with missing …

…@param or @return

Signed-off-by: Lukas Jungmann <lukas.jungmann@oracle.com>

jaxb-ri/docs/release-documentation/src/docbook/jaxb-changelog.xml

@@ -38,6 +38,9 @@
                     <listitem><para>
                         <link xlink:href="https://github.com/eclipse-ee4j/jaxb-ri/issues/1053">#1053</link>: Use Java 7 diamond operator
                     </para></listitem>
+                    <listitem><para>
+                        <link xlink:href="https://github.com/eclipse-ee4j/jaxb-ri/issues/1117">#1117</link>: xjc-generated classes may have methods with missing @param or @return
+                    </para></listitem>
                     <listitem><para>
                         <link xlink:href="https://github.com/eclipse-ee4j/jaxb-ri/issues/1489">#1489</link>: DOMScanner ignores default namespace at scan method
                     </para></listitem>

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/Plugin.java

@@ -69,8 +69,8 @@ protected Plugin() {
     public abstract String getUsage();
 
     /**
-     * Parses an option <code>args[i]</code> and augment
-     * the <code>opt</code> object appropriately, then return
+     * Parses an option {@code args[i]} and augment
+     * the {@code opt} object appropriately, then return
      * the number of tokens consumed.
      *
      * <p>

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

@@ -757,7 +757,7 @@ private void generateEnumBody(EnumOutline eo) {
      * Determines the FieldRenderer used for the given FieldUse,
      * then generates the field declaration and accessor methods.
      *
-     * The <code>fields</code> map will be updated with the newly
+     * The {@code fields} map will be updated with the newly
      * created FieldRenderer.
      */
     private FieldOutline generateFieldDecl(ClassOutlineImpl cc, CPropertyInfo prop) {

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

@@ -14,7 +14,7 @@
 import com.sun.tools.xjc.model.CElementInfo;
 
 /**
- * Generates <code>ObjectFactory</code> then wraps it and provides
+ * Generates {@code ObjectFactory} then wraps it and provides
  * access to it.
  *
  * <p>

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2022 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
@@ -42,7 +42,7 @@
 import org.glassfish.jaxb.core.v2.TODO;
 
 /**
- * Generates <code>ObjectFactory</code> then wraps it and provides
+ * Generates {@code ObjectFactory} then wraps it and provides
  * access to it.
  *
  * <p>
@@ -294,6 +294,9 @@ protected final void populate( ClassOutlineImpl cc, JClass sigType ) {
             m.javadoc()
                 .append("Create an instance of ")
                 .append(cc.ref);
+            m.javadoc().addReturn()
+                .append("the new instance of ")
+                .append(cc.ref);
         }
 
 
@@ -336,6 +339,9 @@ protected final void populate( ClassOutlineImpl cc, JClass sigType ) {
                 .append( "Create an instance of " )
                 .append( cc.ref )
                 .addThrows(JAXBException.class).append("if an error occurs");
+            m.javadoc().addReturn()
+                    .append("the new instance of ")
+                    .append(cc.ref);
 
             // constructor
             // [RESULT]
@@ -358,10 +364,16 @@ protected final void populate( ClassOutlineImpl cc, JClass sigType ) {
 
                 // declare a parameter on this factory method and set
                 // it to the field
-                inv.arg(m.param( fo.getRawType(), fieldName ));
+                JVar $var = m.param(fo.getRawType(), fieldName);
+                inv.arg($var);
+                m.javadoc().addParam($var)
+                        .append("Java instance representing xml element's value.");
 
-                JVar $var = c.param( fo.getRawType(), fieldName );
+                $var = c.param( fo.getRawType(), fieldName );
                 accessor.fromRawValue(c.body(),'_'+fieldName,$var);
+                // describe a parameter in a javadoc
+                c.javadoc().addParam($var)
+                        .append("Java instance representing xml element's value.");
             }
         }
     }

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

@@ -112,7 +112,7 @@ public void generateAccessors() {
             "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</CODE> method for the " +pname+ " property.\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"+
@@ -126,6 +126,8 @@ public void generateAccessors() {
             "<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.");
     }
 
     @Override

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

@@ -115,7 +115,7 @@ public void generateAccessors() {
             "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</CODE> method for the " +pname+ " property.\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"+
@@ -129,6 +129,8 @@ public void generateAccessors() {
             "<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.");
     }
 
     @Override

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

@@ -110,7 +110,7 @@ public void generateAccessors() {
             "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</CODE> method for the " +pname+ " property.\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"+
@@ -124,6 +124,8 @@ public void generateAccessors() {
             "<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.");
     }
 
     @Override

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/outline/Outline.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2022 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
@@ -90,7 +90,7 @@ public interface Outline {
 
     /**
      * Gets a reference to
-     * <code>new CodeModelClassFactory(getErrorHandler())</code>.
+     * {@code new CodeModelClassFactory(getErrorHandler())}.
      */
     CodeModelClassFactory getClassFactory();
 

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/reader/xmlschema/BGMBuilder.java

@@ -323,7 +323,7 @@ private void populate( Map<String,? extends XSComponent> col, XSSchema schema )
     }
 
     /**
-     * Generates <code>package.html</code> if the customization
+     * Generates {@code package.html} if the customization
      * says so.
      */
     private void processPackageJavadoc( XSSchema s ) {

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/reader/xmlschema/DefaultClassBinder.java

@@ -368,7 +368,7 @@ public CClassInfo schema(XSSchema schema) {
      *      return value is unused. Since most of the caller needs to
      *      return null, to make the code a little bit shorter, this
      *      method always return null (so that the caller can always
-     *      say <code>return never(sc);</code>.
+     *      say {@code return never(sc);}.
      */
     private CClassInfo never() {
         // all we need to do here is just not to acknowledge

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/reader/xmlschema/bindinfo/BIProperty.java

@@ -68,8 +68,8 @@
  * into a Java property (some restrictions apply.)
  * 
  * <p>
- * All the getter methods (such as <code>getBaseType</code> or
- * <code>getBindStyle</code>) honors the delegation chain of
+ * All the getter methods (such as {@code getBaseType} or
+ * {@code getBindStyle}) honors the delegation chain of
  * property customization specified in the spec. Namely,
  * if two property customizations are attached to an attribute
  * use and an attribute decl, then anything unspecified in the

jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/reader/xmlschema/ct/CTBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2022 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
@@ -41,7 +41,7 @@ abstract class CTBuilder {
 
     /**
      * Binds the given complex type. This method will be called
-     * only when the <code>isApplicable</code> method returns true.
+     * only when the {@code isApplicable} method returns true.
      */
     abstract void build(XSComplexType ct);