jaxb-ri
jaxb-ri copied to clipboard
eclipse-ee4j
More Schema Annotations/Documentation to Javadoc
As discussed on the "Schema Annotations/Documentation to Javadoc" thread on [email protected] (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]
- Issue Imported From: https://github.com/javaee/jaxb-v2/issues/172
- Original Issue Raised By:@glassfishrobot
- Original Issue Assigned To: @glassfishrobot
@glassfishrobot Commented kohsuke said: Created an attachment (id=105) Schema I used to test the problem.
@glassfishrobot Commented kohsuke said: Also in this category is javadoc for enumeration values.
@glassfishrobot Commented kohsuke said:
-
-
- Issue 431 has been marked as a duplicate of this issue. ***
-
@glassfishrobot Commented 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 Commented olo said: CCing myself (Bugzilla doesn't allow without a comment).
@glassfishrobot Commented dkulp said: This is also the blocker for a CXF issue:
https://issues.apache.org/jira/browse/CXF-2486
@glassfishrobot Commented 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 Commented 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 Commented 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 Commented 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>
- 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");
- 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");
- 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 Commented 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 Commented 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
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 Commented vorburger said: #839 (new) created to avoid this being swiped under the carpet.
@glassfishrobot Commented snajper said: Understood, thanks for the clarifications here.
@glassfishrobot Commented kwakeroni said: Just wanted to indicate that the reverse might also be useful: include javadocs as annotation/documentation in the generated xsd.
@glassfishrobot Commented duncant said: This would be extremely useful, in both directions. Hoping for a fix!
@glassfishrobot Commented This issue was imported from java.net JIRA JAXB-172
Still having issues to generate Javadoc from documented elements:
<complexType name="SomeType"> <sequence> <element name="someProperty" type="string" > <annotation> <documentation>Some documentation.</documentation> </annotation> </element> </sequence> </complexType>
