JDK-8158221 : ObjectFactory generated by xjc (jaxb) has incomplete/invalid javadoc comments
  • Type: Bug
  • Component: xml
  • Sub-Component: jaxb
  • Affected Version: 8,9
  • Priority: P3
  • Status: Closed
  • Resolution: Duplicate
  • OS: linux
  • CPU: x86_64
  • Submitted: 2015-12-02
  • Updated: 2016-12-26
  • Resolved: 2016-12-26
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 9
9Resolved
Related Reports
Duplicate :  
JDK-8164479 - Update JAX-WS RI integration to latest version (2.3.0-SNAPSHOT)
Description
FULL PRODUCT VERSION :
*  /usr/lib/jvm/java-8-oracle/jre/bin/java -version
java version "1.8.0_60"
Java(TM) SE Runtime Environment (build 1.8.0_60-b27)
Java HotSpot(TM) 64-Bit Server VM (build 25.60-b23, mixed mode)

ADDITIONAL OS VERSION INFORMATION :
Linux lenovo-t430u 3.16.0-33-generic #44-Ubuntu SMP Thu Mar 12 12:19:35 UTC 2015 x86_64 x86_64 x86_64 GNU/Linux

EXTRA RELEVANT SYSTEM CONFIGURATION :
*  /usr/lib/jvm/java-8-oracle/bin/xjc -version
xjc 2.2.8-b130911.1802


A DESCRIPTION OF THE PROBLEM :
When generating Java-classes with jaxb (xjc) the generated ObjectFactory will contain malformed or invalid javadoc comments. This will result in javadoc warnings and a failure when generating the javadoc with the default configuration from the maven-javadoc-plugin.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Generate java-classes from a xml with xjc and generate javadoc from the generated files.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
0 javadoc warnings
ACTUAL -
Constructing Javadoc information...
Standard Doclet version 1.8.0_60
Building tree for all the packages and classes...
Generating ./src/main/resources/com/example/ObjectFactory.html...
./src/main/java/com/example/ObjectFactory.java:41: warning: no @param for value
    public JAXBElement<String> createJaxExample(String value) {
                               ^
./src/main/java/com/example/ObjectFactory.java:41: warning: no @return
    public JAXBElement<String> createJaxExample(String value) {
                               ^
Generating ./src/main/resources/com/example/package-frame.html...
Generating ./src/main/resources/com/example/package-summary.html...
Generating ./src/main/resources/com/example/package-tree.html...
Generating ./src/main/resources/constant-values.html...
Building index for all the packages and classes...
Generating ./src/main/resources/overview-tree.html...
Generating ./src/main/resources/index-all.html...
Generating ./src/main/resources/deprecated-list.html...
Building index for all classes...
Generating ./src/main/resources/allclasses-frame.html...
Generating ./src/main/resources/allclasses-noframe.html...
Generating ./src/main/resources/index.html...
Generating ./src/main/resources/help-doc.html...
2 warnings


REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
#!/bin/bash
BASE_PATH_FOR_JAVA="./src/main/java/"
BASE_PATH_FOR_JAVADOC="./src/main/resources/"

XSD_CONTENT='<?xml version="1.0"?>\n
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">\n
 <xsd:element name="JaxExample" type="xsd:string"/>\n
</xsd:schema>\n'

XSD_FILE="./demo.xsd"
echo -e ${XSD_CONTENT} > ${XSD_FILE}


mkdir -p ${BASE_PATH_FOR_JAVA}
mkdir -p ${BASE_PATH_FOR_JAVADOC}

xjc -d ${BASE_PATH_FOR_JAVA} -p com.example -xmlschema -no-header ${XSD_FILE}

javadoc -d ${BASE_PATH_FOR_JAVADOC} com.example -sourcepath ${BASE_PATH_FOR_JAVA}

---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
Add missing javadoc comments (manually); need to this step after each generation of the java classes.
Comments
This bug was fixed by bringing latest JAXWS-RI changes into JDK9, see JDK-8164479
26-12-2016
The following preliminary patch solves the reported problem in JDK8 source base: diff -r 2e7f62568785 src/share/jaxws_classes/com/sun/tools/internal/xjc/generator/bean/ObjectFactoryGeneratorImpl.java --- a/src/share/jaxws_classes/com/sun/tools/internal/xjc/generator/bean/ObjectFactoryGeneratorImpl.java Mon Jul 25 15:07:28 2016 -0700 +++ b/src/share/jaxws_classes/com/sun/tools/internal/xjc/generator/bean/ObjectFactoryGeneratorImpl.java Wed Aug 24 19:57:01 2016 +0300 @@ -229,8 +229,10 @@ m.javadoc() .append("Create an instance of ") - .append(exposedElementType) - .append("}"); + .append(exposedElementType); + m.javadoc().addParam($value).append("allowed object is ") + .append(exposedType); + m.javadoc().addReturn().append("Instance of").append(exposedElementType); XmlElementDeclWriter xemw = m.annotate2(XmlElementDeclWriter.class); xemw.namespace(namespaceURI).name(localPart);
24-08-2016
This is a regression, the test case yields expected results upto 7u80 and starts throwing warnings from JDK 8 onwards. JDK 7u80- pass JDK 8 - Fail JDK 8u90 - Fail JDK 9ea - Fail Here are the outputs on various versions: JDK 7u80: --------------- -bash-4.2$ ./script.sh parsing a schema... compiling a schema... com/example/ObjectFactory.java Loading source files for package com.example... Constructing Javadoc information... Standard Doclet version 1.7.0_80 Building tree for all the packages and classes... Generating {BASE_PATH_FOR_JAVADOC}/com/example/ObjectFactory.html... Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-frame.html... Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-summary.html... Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-tree.html... Generating {BASE_PATH_FOR_JAVADOC}/constant-values.html... Building index for all the packages and classes... Generating {BASE_PATH_FOR_JAVADOC}/overview-tree.html... Generating {BASE_PATH_FOR_JAVADOC}/index-all.html... Generating {BASE_PATH_FOR_JAVADOC}/deprecated-list.html... Building index for all classes... Generating {BASE_PATH_FOR_JAVADOC}/allclasses-frame.html... Generating {BASE_PATH_FOR_JAVADOC}/allclasses-noframe.html... Generating {BASE_PATH_FOR_JAVADOC}/index.html... Generating {BASE_PATH_FOR_JAVADOC}/help-doc.html... JDK 8u92: --------------- -bash-4.2$ ./script.sh parsing a schema... compiling a schema... com/example/ObjectFactory.java Loading source files for package com.example... Constructing Javadoc information... Standard Doclet version 1.8.0_92 Building tree for all the packages and classes... Generating {BASE_PATH_FOR_JAVADOC}/com/example/ObjectFactory.html... ./src/main/java/com/example/ObjectFactory.java:41: warning: no @param for value public JAXBElement<String> createJaxExample(String value) { ^ ./src/main/java/com/example/ObjectFactory.java:41: warning: no @return public JAXBElement<String> createJaxExample(String value) { ^ Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-frame.html... Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-summary.html... Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-tree.html... Generating {BASE_PATH_FOR_JAVADOC}/constant-values.html... Building index for all the packages and classes... Generating {BASE_PATH_FOR_JAVADOC}/overview-tree.html... Generating {BASE_PATH_FOR_JAVADOC}/index-all.html... Generating {BASE_PATH_FOR_JAVADOC}/deprecated-list.html... Building index for all classes... Generating {BASE_PATH_FOR_JAVADOC}/allclasses-frame.html... Generating {BASE_PATH_FOR_JAVADOC}/allclasses-noframe.html... Generating {BASE_PATH_FOR_JAVADOC}/index.html... Generating {BASE_PATH_FOR_JAVADOC}/help-doc.html... 2 warnings JDK 9ea ------------- -bash-4.2$ ./script.sh parsing a schema... compiling a schema... com/example/ObjectFactory.java Loading source files for package com.example... Constructing Javadoc information... ./src/main/java/com/example/ObjectFactory.java:4: error: package javax.xml.bind does not exist import javax.xml.bind.JAXBElement; ^ ./src/main/java/com/example/ObjectFactory.java:5: error: package javax.xml.bind.annotation does not exist import javax.xml.bind.annotation.XmlElementDecl; ^ ./src/main/java/com/example/ObjectFactory.java:6: error: package javax.xml.bind.annotation does not exist import javax.xml.bind.annotation.XmlRegistry; ^ ./src/main/java/com/example/ObjectFactory.java:24: error: cannot find symbol @XmlRegistry ^ symbol: class XmlRegistry ./src/main/java/com/example/ObjectFactory.java:41: error: cannot find symbol public JAXBElement<String> createJaxExample(String value) { ^ symbol: class JAXBElement location: class ObjectFactory ./src/main/java/com/example/ObjectFactory.java:40: error: cannot find symbol @XmlElementDecl(namespace = "", name = "JaxExample") ^ symbol: class XmlElementDecl location: class ObjectFactory Standard Doclet version 9-ea Building tree for all the packages and classes... Generating {BASE_PATH_FOR_JAVADOC}/com/example/ObjectFactory.html... ./src/main/java/com/example/ObjectFactory.java:37: error: reference not found * Create an instance of {@link JAXBElement }{@code <}{@link String }{@code >}} ^ ./src/main/java/com/example/ObjectFactory.java:41: warning: no @param for value public JAXBElement<String> createJaxExample(String value) { ^ Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-frame.html... Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-summary.html... Generating {BASE_PATH_FOR_JAVADOC}/com/example/package-tree.html... Generating {BASE_PATH_FOR_JAVADOC}/constant-values.html... Building index for all the packages and classes... Generating {BASE_PATH_FOR_JAVADOC}/overview-tree.html... Generating {BASE_PATH_FOR_JAVADOC}/index-all.html... Generating {BASE_PATH_FOR_JAVADOC}/deprecated-list.html... Building index for all classes... Generating {BASE_PATH_FOR_JAVADOC}/allclasses-frame.html... Generating {BASE_PATH_FOR_JAVADOC}/allclasses-noframe.html... Generating {BASE_PATH_FOR_JAVADOC}/index.html... Generating {BASE_PATH_FOR_JAVADOC}/help-doc.html... 1 error 7 warnings
31-05-2016