Thanks as always for your prompt feedback and a great product.
"It simply isn't as important as supporting more of the W3C XML Schema spec"
I agree 100%, don't let this feature request get in the way of full XML
Schema support.
"As Ed pointed out, you can duplicate the annotation documentation in
javadoc customizations for the time being."
Indeed, it's just not _that_ important to us for us to do the extra work and
make our bindings file more complicated (not that much more complicated I
know). It's a feature that will be nice to get for "free" at some point in
the future.
Note that the current 1.0.1 Javadoc comment generated is slightly
misleading. For example, the following XSD fragment:
<xs:attribute name="maxTotalConnections" type="cics:positiveShort"
use="optional" default="20">
Yields the following Javadoc fragment:
<attribute name="maxTotalConnections"
type="{
http://www.seagullsw.com/appinterface/server/backend/cics/bind}positi
veShort" />
Note that nothing is said of:
use="optional" default="20"
Which are very important data points! (and std XSD attributes).
Thanks,
Gary
-----Original Message-----
From: Ryan Shoemaker - JavaSoft East [mailto:Ryan.Shoemaker_at_Sun.COM]
Sent: Wednesday, June 25, 2003 08:07
To: JAXB-INTEREST_at_JAVA.SUN.COM
Subject: Re: XSD annotation/documentation to Javadoc request
Gary Gregory wrote:
> Hello,
>
> It would be quite helpful if XSD annotations would show up as Javadoc
> comments.
>
Agreed. The specification left some wiggle room to not implement it:
"Class-level javadoc is a combination of a documentation annotation from the
schema component and/or javadoc specified within customization."
There are similar statements all over the spec for other schema components.
It simply isn't as important as supporting more of the W3C XML Schema spec,
so we haven't implemented it yet, but it's still on our list of things to
implement - we'll make sure to consider it more seriously now that we've
gotten feedback that people are interested in it.
As Ed pointed out, you can duplicate the annotation documention in javadoc
customizations for the time being.
Thanks for the feedback...
--Ryan
> For example, the following:
>
> <xs:attribute name="maxConnectionsPerHost"
> type="cics:positiveShort" use="optional" default="2">
> <xs:annotation>
> <xs:documentation>Sets the maximum number of
> connections allowed for a given HostConfiguration. Per RFC 2616
> section 8.1.4, this value defaults to 2.</xs:documentation>
>
> </xs:annotation>
> </xs:attribute>
>
> Would show up as:
>
> /**
> * Sets the maximum number of connections allowed for a
> * given HostConfiguration. Per RFC 2616 section 8.1.4,
> * this value defaults to 2.
> */
>
> I've formatted this so it fits nicely in an email message but I think
> the format should not be changed from what is in the
> annotation/documentation element.
>
> The reason I bring this is up is that some tools like XMLSpy support
> this scheme to document XSDs, which is how we document our XSDs.
>
> Gary
>