如何使生成的类包含XML Schema文档中的Javadoc [英] How to make generated classes contain Javadoc from XML Schema documentation

问题描述

我目前正在处理一个XML Schema，它具有< xsd：annotation> / < xsd：documentation> 关于大多数类型和元素。当我从这个XML Schema生成Java Bean时，那些Beans的Javadoc只包含一些关于类型/元素允许内容的通用生成信息。

I'm currently working with an XML Schema that has <xsd:annotation>/<xsd:documentation> on most types and elements. When I generate Java Beans from this XML Schema, then the Javadoc of those Beans only contains some generic generated information about the allowed content of the type/element.

我是喜欢在相关位置查看< xsd：documentation> 标记的内容（例如，该标记的内容应显示在该文本的Javadoc中生成的类来表示complexType）。

I'd like to see the content of the <xsd:documentation> tag in the relevant places (for example the content of that tag for a complextType should show up in the Javadoc of the class generated to represent that complexType).

有没有办法实现这个目标？

Is there any way to achieve this?

编辑：此XML Schema将在带有JAX-WS的WSDL中使用，因此该标记也可能是合适的。

Edit: this XML Schema will be used in a WSDL with JAX-WS, so this tag might be appropriate as well.

编辑2 ：我读过< jxb：javadoc> 。根据我的理解，我可以在单独的JAXB绑定文件中或直接在XML Schema中指定。这几乎可以解决我的问题。但我宁愿使用现有的< xsd：documentation> 标签，因为Javadoc不是文档的主要目标（它主要是关于数据结构的信息而不是关于从它生成的Java Bean）并允许非JAXB工具访问信息。提供< jxb：javadoc> 和 xsd：documentation> 中的文档感觉错了，因为我' m没有充分理由重复数据（和工作）。

Edit 2: I've read about <jxb:javadoc>. From what I understand I can specify that either in a separate JAXB binding file or directly in the XML Schema. That would almost solve my problem. But I'd rather use the existing <xsd:documentation> tag, since Javadoc is not the primary target of the documentation (it's information about the data structure primarily and not about the Java Beans generated from it) and to allow non-JAXB tools to access the information as well. Providing the documentation in both <jxb:javadoc> and xsd:documentation> "feels" wrong, because I'm duplicating data (and work) for no good reason.

编辑3 ：感谢Pascal的回答我意识到我已经有了一半解决方案：将< xsd：documentation> 的 complexType 写入其Javadoc的开头！问题仍然是仅使用 complexType s和 simpleType s（可以也导致一个类）和元素仍然是Javadoc-less。

Edit 3: Thanks to the answer by Pascal I realized that I already have half a solution: The <xsd:documentation> of complexTypes is written to the beginning of its Javadoc! The problem is still that only that complexTypes is used and simpleTypes (which can also result in a class) and elements are still Javadoc-less.

推荐答案

我从来没能得到常规 xsd：documentation 放在java源代码中，除非当且仅当是复杂类型时。元素，简单类型，
等的文档将被忽略。

I've never been able to get regular xsd:documentation to be placed in the java source except if and only if it was a Complex Type. Documentation for elements, simple types, etc are ignored.

所以，我最终使用 jxb：javadoc 。为此，请在中包含 xmlns：jxb =http://java.sun.com/xml/ns/jaxb的定义< xsd：schema> 元素。

So, I end up using jxb:javadoc. To do so, include the definition of xmlns:jxb="http://java.sun.com/xml/ns/jaxb" in your <xsd:schema> element.

将子项添加到< xsd：complexType> 或< xsd：element> 或< xsd：attribute> ：

<xsd:annotation><xsd:appinfo><jxb:XXX><jxb:javadoc>
  This is my comment for a class/property
</jxb:javadoc></jxb:XXX></xsd:appinfo></xsd:annotation>

其中XXX是类或财产。

Where XXX is either "class" or "property".

对于一个包你写一个孩子到 xsd：schema

For a package you write a child to xsd:schema

<xsd:annotation><xsd:appinfo><jxb:schemaBindings><jxb:package name="com.acme"><jxb:javadoc>
  This is my comment for a package
</jxb:javadoc></jxb:package></jxb:schemaBindings></xsd:appinfo></xsd:annotation>

编写HTML文档需要用<！[CDATA [---]进行包围]]>

Writing HTML document requires bracketing with <![CDATA[ --- ]]>

（编辑：在写我的答案时，问题已由OP编辑，所以我相应地更新了它）

( While writing my answer, the question has been edited by the OP so I'm updating it accordingly)

在我的情况下，javadoc是唯一的目标，因此可以使用 jxb：javadoc 。但是你的更新很有意义，实际上，我完全赞同你。可悲的是，我从来没有为你描述的情况找到理想的解决方案（因此我会非常仔细地遵循这个问题）。也许您可以使用 xframe 之类的内容从 xsd生成文档：文档，但这不回答问题。

In my case, javadoc was the only target so it was acceptable to use jxb:javadoc. But your update makes perfect sense and, actually, I totally agree with you. Sadly, I never found an ideal solution for the situation you describe (so I'll follow this question very carefully). Maybe you could use something like xframe to generate documentation from xsd:documentation, but this doesn't answer the question.

这篇关于如何使生成的类包含XML Schema文档中的Javadoc的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！