如何使生成的类包含XML Schema文档中的Javadoc

Question

我目前正在与具有XML Schema工作<xsd:annotation>/ <xsd:documentation>对大多数类型和元素.当我从这个XML Schema生成Java Bean时,那些Beans的Javadoc只包含一些关于类型/元素的允许内容的通用生成信息.

我希望<xsd:documentation>在相关位置看到标记的内容(例如,对于ComplextType,该标记的内容应该显示在生成的类的Javadoc中以表示该complexType).

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

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

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

编辑3:多亏了帕斯卡的答案,我意识到,我已经有半个解决方案:<xsd:documentation>的complexTypes的写入它的Javadoc的开始!问题仍然是只有该complexTypeS用于和simpleTypeS(这也可导致在一个类)和元素仍然Javadoc的更小.

Answer 1

我从来没有能够定期xsd:documentation被放置在java源代码中,除非且仅当它是复杂类型时.元素,简单类型等的文档将被忽略.

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

孩子添加到<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是"类"或"财产"的地方.

对于一个包,你写一个孩子 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[ --- ]]>

(编辑:在写我的答案时,问题已由OP编辑,所以我相应地更新它)

就我而言,javadoc是唯一的目标,因此可以使用jxb:javadoc.但是你的更新很有意义,实际上,我完全赞同你.可悲的是,我从来没有为你描述的情况找到理想的解决方案(所以我会非常仔细地遵循这个问题).也许你可以使用像xframe这样的东西来生成文档xsd:documentation,但这不能回答这个问题.

Answer 2

这对于JAXB参考实现是不可能的.即使您尝试编写XJC插件,您也会发现插件API没有引用Schema定义,因此无法提取此信息.

我们唯一的希望是未来版本的JAXB能够解决这个问题.这里有一个开放的功能请求.

Answer 3

我发现以下技术对于将 JavaDoc 标头添加到 Java 元素类（从 XML 模式生成）非常有效。我将 JavaDoc 嵌套在 jax-b 命名空间中定义的标记中，嵌套在 xml 模式注释和 appinfo 标记中。注意 jaxb 命名空间定义了文档标签的类型；我使用其中的两个：类标签和属性标签。在以下命名空间中定义： xmlns:jxb="http://java.sun.com/xml/ns/jaxb"

1）为了记录一个类，我按以下顺序使用 jaxb“class”标签：

  <xs:complexType name="Structure">
     <xs:annotation>
        <xs:appinfo>
           <jxb:class>
              <jxb:javadoc>
                 Documentation text goes here. Since parsing the schema  
                 into Java involves evaluating the xml, I escape all 
                 the tags I use as follows &lt;p&gt; for <p>.
              </jxb:javadoc>
           </jxb:class>
        </xs:appinfo>
     </xs:annotation>

     .
     .
     .
  </xs:complexType>

2）为了记录元素，我使用“property”标签，如下所示：

       <xs:element name="description" type="rep:NamedString">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </jxb:javadoc>
                </jxb:property>
             </xs:appinfo>
          </xs:annotation>
       </xs:element>

3）我使用同一组标签来记录属性：

      <xs:attribute name="name" type="xs:NCName" use="required">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </jxb:javadoc>
                </jxb:property>
             </xs:appinfo>
          </xs:annotation>
       </xs:attribute>

4）为了记录选择，我使用属性 jaxb 标签，并记录选择。

    <xs:choice maxOccurs="unbounded">
          <xs:annotation>
             <xs:appinfo>
                <jxb:property>
                   <jxb:javadoc>
                      &lt;p&gt;Documentation goes here.&lt;/p&gt;
                   </jxb:javadoc>
                </jxb:property>
             </xs:appinfo>
          </xs:annotation>

          <xs:element name="value" type="rep:NamedValue" />
          <xs:element name="list" type="rep:NamedList" />
          <xs:element name="structure" type="rep:NamedStructure" />
       </xs:choice>

尝试在此处记录各个选择将会失败，因为此标记会生成非类型化列表。