More Schema Annotations/Documentation to Javadoc

[glassfishrobot]

As discussed on the "Schema Annotations/Documentation to Javadoc" thread on
users@jaxb.dev.java.net (see
https://jaxb.dev.java.net/servlets/ReadMsg?list=users&msgNo=5469) :

If you find cases where it doesn't work as you expected,

. not the same complexType's sequence/element* documentation (which
I'd think you'd expect on the respective getters/setters, instead of
that pretty useless "Gets the value of the ... property."), nor a
simpleType's annotation/documentation that turns into a @XmlEnum
public enum, where one would expect both JavaDoc of the class as well
as the individual enum values, from the
simpleType/restriction/enumeration/annotation/documentation.
(Additionally maybe putting schema/annotation/documentation into
package-info.java as JavaDoc; although not sure how to deal with one
namespace schema in several .xsd... not sure how that looks in XSOM by
the time you process this?)

Please let me know if you need more details, schemas or code - hoping above is
clear.

When you do commit code for this, I'd would be happy to try a nightly build and
provide feedback; please add a comment to this Bugzilla and we'll give the next
build a shot. Thanks!

Environment

Operating System: All
Platform: All
URL: https://jaxb.dev.java.net/servlets/ReadMsg?list=users&msgNo=5469

Affected Versions

[2.0 FCS]

[glassfishrobot]

Reported by vorburger

[glassfishrobot]

Issue-Links:
is duplicated by
JAXB-839

[glassfishrobot]

Was assigned to snajper

[glassfishrobot]

kohsuke said:
Created an attachment (id=105)
Schema I used to test the problem.

[glassfishrobot]

File: test.xsd
Attached By: kohsuke

[glassfishrobot]

vorburger said:
FYI: http://jira.codehaus.org/browse/XFIRE-507

[glassfishrobot]

kohsuke said:
Also in this category is javadoc for enumeration values.

[glassfishrobot]

kohsuke said:

• • • Issue 431 has been marked as a duplicate of this issue. ***

[glassfishrobot]

kohsuke said:
issue #431 that was marked as a duplicate for this had 25 votes on its own, so
this appears to be a highly requested feature.

[glassfishrobot]

olo said:
CCing myself (Bugzilla doesn't allow without a comment).

[glassfishrobot]

dkulp said:
This is also the blocker for a CXF issue:

https://issues.apache.org/jira/browse/CXF-2486

[glassfishrobot]

skells said:
I have a plugin that adds documentation to the getters, setters and the fields,
that works withthe placement that xmlspy used for the documentation. I would
not say that it is complete, but it works OK for the cases that we use.

Theer are some problems with it mostly related to the API the generate the
javadoc, and I would not say that the code is clean ....

I can share the code if anyone is interested in taking it forward

[glassfishrobot]

dkulp said:
If you'd like to donate the code to CXF, we could certainly use it. CXF
already has a couple plugins to workaround XJC issues.

Just log a JIRA at:
https://issues.apache.org/jira/browse/CXF
and attach the code.

[glassfishrobot]

dkulp said:
skells,

In CXF, we've recently setup a subproject to house additional XJC plugins
that the community finds useful. We'd love to have your contribution if the
offer still stands.

[glassfishrobot]

kpsdevi said:
The schema is provided by the service provider and they have defined integer enumeration values with documentation but without names as given below.
<xsd:simpleType name="XYZCodeSimpleType">
xsd:annotation
xsd:documentationA data type for an enumeration of XYZ Codes.</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:token">
<xsd:enumeration value="0">
xsd:annotation
xsd:documentationUndefined</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="1">
xsd:annotation
xsd:documentationLeft</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="2">
xsd:annotation
xsd:documentationRight</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>

1. JAXB 2 has not generated classes for those enum types. So I added global bindings as given below

<jaxb:globalBindings typesafeEnumMemberName="generateName">

Then I was able to generate classes as given below with prefix "VALUE_" in the name, which was confusing as my enum values start with 0.

public enum XYZCodeSimpleType {

/**

• Undefined
• */
  @XmlEnumValue("0")
  VALUE_1("0"),

/**

• Left
• */
  @XmlEnumValue("1")
  VALUE_2("1"),

/**

• Right
• */
  @XmlEnumValue("2")
  VALUE_3("2");

2. So I have used external bindings to define name as given below.

<jaxb:bindings node="//xsd:simpleType[@name='XYZSimpleType']">
jaxb:typesafeEnumClass
<jaxb:typesafeEnumMember value="0" name="UNDEFINED" />
<jaxb:typesafeEnumMember value="1" name="LEFT" />
<jaxb:typesafeEnumMember value="2" name="RIGHT" />
</jaxb:typesafeEnumClass>
</jaxb:bindings>

With this external binding I was able to generate classes with names as given below but I lost the documentation which is there in the schema. Because of that I need to duplicate documentation as well in jaxb bindings which I don't want to.

public enum XYZCodeSimpleType {

@XmlEnumValue("0")
UNDEFINED("0"),
@XmlEnumValue("1")
LEFT("1"),
@XmlEnumValue("2")
RIGHT("2");

3. I looked at JAXB 2.2.3 source code and figured out the cause of this issue. Issue is in the method "buildCEnumConstants" of "com.sun.tools.xjc.reader.xmlschema.SimpleTypeBuilder". The documentation from schema is getting overwritten even when the javadoc is not specified in the bindings and getting nullified if there is no value in the bindings.

if( mem!=null )

{ name = mem.name; mdoc = mem.javadoc; }

So the above code should be modified as given below

if( mem!=null ) {
name = mem.name;
if (mem.javadoc!=null)

{ //Fix mdoc = mem.javadoc; }

}

I request you to fix this issue and release the update of JAXB2.2.3 as soon as possible.

[glassfishrobot]

snajper said:
Unfortunately have to close this one as incomplete because the original thread wast lost and I'm not able to grasp the roots of the bug here. Recently I fixed one javadoc issue with enums thanks to a specific submission, but other than that I think I need more info on what is requested here. Feel free to reopen if you have that. Thanks.

[glassfishrobot]

os111 said:
Not sure why this was closed?

As I understood it the original intent was to include documentations from the XSD in the Javadoc of autogenerated code.

For example the following from schema snippet

This attribute can be either 1, 2, or 3.

Generates the following javadoc:

/**

• Gets the value of the documentedAttribute property.

• @return

• possible object is

• {@link String }

• */

The javadoc should also include the schema's documentation.

[glassfishrobot]

vorburger said:
#839 (new) created to avoid this being swiped under the carpet.

[glassfishrobot]

snajper said:
Understood, thanks for the clarifications here.

[glassfishrobot]

marcelstoer said:
Just found here thanks to a really helpful SO answer.

[glassfishrobot]

kwakeroni said:
Just wanted to indicate that the reverse might also be useful: include javadocs as annotation/documentation in the generated xsd.

[glassfishrobot]

duncant said:
This would be extremely useful, in both directions. Hoping for a fix!

[glassfishrobot]

This issue was imported from java.net JIRA JAXB-172