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

问题描述

我目前正在使用一个 XML 模式，该模式在大多数类型和元素上具有 /.当我从这个 XML Schema 生成 Java Bean 时，这些 Bean 的 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> 标签的内容(例如，complextType 标签的内容应该显示在生成的类来表示那个 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 模式将在带有 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:我已经阅读了 .据我所知，我可以在单独的 JAXB 绑定文件中或直接在 XML 模式中指定.那几乎可以解决我的问题.但我宁愿使用现有的 <xsd:documentation> 标记，因为 Javadoc 不是文档的主要目标(它主要是关于数据结构的信息，而不是关于从它生成的 Java Beans) 并允许非 JAXB 工具访问该信息.在 和 xsd:documentation> 中提供文档感觉"是错误的，因为我无缘无故地复制数据(和工作).

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 的回答，我意识到我已经有了一半的解决方案:complexTypecode>s 写在它的 Javadoc 的开头！问题仍然是 only 使用 complexTypes 和 simpleTypes(也可以产生一个类)和元素仍然是 Javadoc-少.

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.

推荐答案

除了 if and only如果它是一个复杂类型.元素、简单类型的文档，等被忽略.

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" 的定义> 元素.

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.

向 或 或 添加子项:

Add a child to <xsd:complexType> or <xsd: element> or <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:documentation 生成文档代码>，但这并没有回答问题.

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屋！