Enrich generated classes with schema documentation

[MrMontag]

In a project I work with hyperjaxb3 and documented schema files.

Schema sample:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb">
    <xs:element name="Lison" type="Lison"/>
    <xs:complexType name="Lison">
        <xs:annotation>
            <xs:documentation>My awesome complex type comment.</xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="Truck" type="xs:string" minOccurs="1" maxOccurs="1">
            <xs:annotation>
                    <xs:documentation>My awesome element comment.</xs:documentation>
                </xs:annotation>
            </xs:element>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

I noticed that only complex type documentation will be considered during the generation process, which is as far as I know related to JAXB.
To solve the issue the idea was to use a binding file including javadoc entries. The binding.xjb could be generated based on the schema in a pre-build step.

Bindings sample:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jaxb:bindings
    version="2.1"
    xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:hj="http://hyperjaxb3.jvnet.org/ejb/schemas/customizations"
    xmlns:orm="http://java.sun.com/xml/ns/persistence/orm"

    jaxb:extensionBindingPrefixes="hj orm">

    <jaxb:bindings schemaLocation="lison.xsd" node="/xs:schema">
        <jaxb:globalBindings generateIsSetMethod="true"/>
        <jaxb:schemaBindings>
            <jaxb:package name="org.xy.luis.generated.lison"/>
        </jaxb:schemaBindings>

        <jaxb:bindings node="xs:complexType[@name='Lison']">
            <jaxb:class>
                <jaxb:javadoc>My awesome complex type comment.</jaxb:javadoc>
            </jaxb:class>
        </jaxb:bindings>

        <jaxb:bindings node="xs:complexType[@name='Lison']/xs:sequence/xs:element[@name='Truck']">
            <jaxb:property>
                <jaxb:javadoc>My awesome element comment.</jaxb:javadoc>
            </jaxb:property>
        </jaxb:bindings>
    </jaxb:bindings>
</jaxb:bindings>

Using the aforementioned approach the get methods will be documented but not the set methods. So I wonder if there is a more elegant way to transfer schema documentation during generation. Are there further configuration possibilities related to documentation in hyperjaxb3? Are there any plans to extend hyperjaxb3 in this direction?

[highsource]

If I understand you correctly, you'd like to add xs:documentation to JavaDoc, right?
If so, is it really specific to Hyperjaxb3?

[MrMontag]

Yes, it is the adoption of xs:documentation to JavaDoc.

I think it is more related to JAXB than Hyperjaxb3. But I'm not sure if the manipulation of the generation process via a bindings.xjb is the best solution for the following workflow.

Schema (with xs:documentation) > Hyperjaxb3 > generated classes (with xs:documenation in JavaDoc)

So based on my XSD and bindings.xjb I would like to have the following generation result.

//...


/**
 * My awesome complex type comment.
 * 
 * 
 * 
 */
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "Lison", propOrder = {
    "truck",
})
@Entity(name = "Lison")
@Table(name = "LISON")
@Inheritance(strategy = InheritanceType.JOINED)
public class Lison
    implements Equals, HashCode
{
    @XmlElement(name = "Truck", required = true)
    protected String truck;

    //...

    /**
     * My awesome element comment.
     * 
     * @return
     *     possible object is
     *     {@link String }
     *     
     */
    @Basic
    @Column(name = "TRUCK", length = 255)
    public String getTruck() {
        return truck;
    }

    /**
     * My awesome element comment.
     * 
     * @param value
     *     allowed object is
     *     {@link String }
     *     
     */
    public void setTruck(String value) {
        this.truck = value;
    }

    @Transient
    public boolean isSetTruck() {
        return (this.truck!= null);
    }

    //...
}

[highsource]

Ok, since it seems to be not in the scope of Hyperjaxb3, I'd suggest to move the issue to JAXB2 Basics (highsource/jaxb2-basics#19).

I generally like the idea but am not sure I'll be able to implement it in the near time.