This week's book giveaway is in the OO, Patterns, UML and Refactoring forum. We're giving away four copies of Refactoring for Software Design Smells: Managing Technical Debt and have Girish Suryanarayana, Ganesh Samarthyam & Tushar Sharma on-line! See this thread for details.
What I want to happen: When the java sources are created, any JavaDoc that was inserted in the XSD should be applied/inserted/added/whatever to the appropriate package|class|property.
Why I want it: As part of a legacy build process, Java sources are generated from the XSDs on each build. Therefore, I can't apply additional JavaDoc to the *.java files, as it would simply be overwritten on the next build. The system is fragile, so correcting the process is not "doable". Therefore, I'm left with trying to find a way to include JavaDoc in the XSD files, and have that travel through the parser to be output in the java source file.
I see examples in various places, but they all seem to involve JAXB. Gleaning from those examples, I have the following...
My expectation is that when I look at the castor generated source files, the class JavaDoc includes the line "Complete ApplyCnamRulesResponse JavaDoc in ApplyCnamRulesResponse.xsd", and "Doc Here" for RetCustSiteNm's JavaDoc.
Unfortunately, I have no idea how people are actually generating JavaDoc using the markup above. They never bother to include the mechanical steps of source production. Given the use of JAXB, I'm guessing there is an obvious step that I just haven't glommed on to.
Or, maybe this simply can't be done and we'll have to live with just the auto-gen'd JavaDoc, rather than being able to also include theory, special usage, etc., as when done by hand.
So, the questions:
1) Is there a way to provide extended JavaDoc commentary/markup in the XSD file, and have that carry through to the generated source?
2) If (1), can the comment be done using straight JavaDoc tags (may have to use CDATA) and not have to rely on some goofy Doclet routine?
3) If (1 && 2), could someone please point me to a documented, --working-- example.