Gary Gregory wrote:
> Thanks as always for your prompt feedback and a great product.
>
Thanks!
>> "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.
>
Understood - I just wanted to make sure you (and everyone else on the list)
knew that there was a workaround.
> 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}positiveShort"
> />
>
> Note that nothing is said of:
>
> use="optional" default="20"
>
> Which are very important data points! (and std XSD attributes).
>
Thanks for the report. Would you be willing to file a bug on this:
http://developer.java.sun.com/developer/bugParade/index.jshtml
Follow the "submit a new bug" link at the bottom of the page.
Thanks,
--Ryan
> 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
> >
>