Great stuff! I've just hit a similar requirement; wanting auto-creation of
the XSD documentation annotations from the Java code, so i'd love a solution
to 369 - will see if I can find some time to help after my upcoming
vacation...
I guess my ideal solution would be; use the JavaDoc comments from the class
/ field / property setter (usually the setter describes the effect of
changing a value along with its possible valid values so often its better
documentation for the schema than the getter; also for some Spring POJOs
there only is a setter).
However sometimes you might wanna write some custom documentation just for
the XSD which differs from the usual javadoc - so I like the idea of using
an annotation such as @XmlDocumentation on a class, field or setter to
replace the javadoc.
i.e. for most things the javadoc will be totally fine; for those places
where its not, use @XmlDocumentation. If some folks wanna use
@XmlDocumentation on every class/field/setter thats cool too.
Incidentally given that this annotation is only gonna be used by the
schemagen tool, its no biggie if its an RI specific extension annotation.
James
Naz Quadri wrote:
>
> Issue 369 has been entered for this.
>
> Kohsuke Kawaguchi wrote:
>
>> Naz Quadri wrote:
>>
>>> Hi,
>>>
>>> I have a set of Java classes which are being used to create an xml
>>> schema using schemagen, or more specifically
>>> JAXBContext.generateSchema(). I would like to be able to add comments
>>> to my classes as annotations if possible and have these injected into
>>> the generated schema as documentation annotations. I'm pretty certain
>>> there is no Java annotation to do this but see below for how it might
>>> look with an invented annotation.
>>
>>
>> Yes, things like this is certainly conceivable.
>>
>> When schemagen acts on the source code it's even possible to just take
>> the javadoc comment.
>>
>>> If this is not possible is there any other way ? Would it be possible
>>> to write the class and field comments into an xml file and hook into
>>> the schemagen process and inject the comments into the schema by
>>> using a plugin of some kind ?
>>
>>
>> Unfortunately right now schema generator class is not extensible. It
>> doesn't have the in-memory mutable tree representation of the schema
>> to be written (unlike XJC), and without it, one cannot really write
>> "plugins" that tweak it before it's written down as schema document.
>>
>> I'm also OK with just adding this capability to the JAXB RI itself
>> without introducing a formal plugin mechanism. Propagating docs seem
>> like a reasonable enough change.
>>
>> If anyone could help us hack the code, that would be great. Otherwise
>> please file this in the issue tracker for future tracking purpose.
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jaxb.dev.java.net
> For additional commands, e-mail: users-help_at_jaxb.dev.java.net
>
>
>
--
View this message in context: http://www.nabble.com/schemagen-and-xsd-documentation-annotations-tf3872846.html#a11517239
Sent from the java.net - jaxb users mailing list archive at Nabble.com.