如何使生成的类包含的Javadoc从XML架构文档

Question

我目前使用具有对大多数类型和元素<xsd:annotation> / <xsd:documentation>一个XML Schema工作。当我生成从该XML模式的Java豆，那么这些豆的Javadoc仅包含关于类型/元件的允许的内容一些通用生成的信息。

我想看到<xsd:documentation>标签中的相关位置（该标签的一个complextType含量应该在产生表示的complexType类的Javadoc显示例如）的含量。

有什么办法来实现这一目标？

修改：这个XML模式将与JAX-WS一个WSDL使用，所以该标签可能是适当的，以及

修改2 ：我读过有关<jxb:javadoc>。据我了解，我可以指定，要么在一个单独的JAXB绑定文件或直接在XML Schema。这几乎可以解决我的问题。但我宁愿使用现有的<xsd:documentation>标签，因为Javadoc中是不是文档的主要目标（这是关于数据结构的信息主要是和不是从它生成的Java Bean）的，并允许非JAXB工具来访问信息为好。提供了两个<jxb:javadoc>和xsd:documentation>的文档“感觉”不对，因为我没有很好的理由复制数据（工作）。

修改3 ：多亏了帕斯卡的答案，我意识到，我已经有一半的解决方案：<xsd:documentation>s的complexType写入其的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没有给出参考架构定义，所以没有办法来提取这些信息。

我们唯一的希望是，JAXB的未来版本中修复的情况。此处有一个开放功能请求。

Answer 3

我发现以下的技术工作得很好，用于将报头的JavaDoc到Java元素类（从XML模式生成）。我窝的JavaDoc在JAX-B命名空间中定义的标签，嵌套在XML模式注释和AppInfo标签内。注意JAXB命名空间定义类型的文档标签;我用两个有：类和属性标记。的xmlns：在以下的命名空间中定义JXB = “http://java.sun.com/xml/ns/jaxb”

1）文件A类，我使用在下面序列的JAXB “类” 标记：

  <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）为了记录一个元素，我使用“属性”标记，如下所示：

       <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）I使用同一组的标记来记录属性：

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

试图在这里记录了个人的选择会失败，因为这个标签 产生一个无类型列表。

Answer 4

特别是对于这种情况下我写XJC插件 XJC的文档的注释-插件

作用：<annotation><documentation> - > Java类注释

说，我们这个对象在XSD描述：

<xs:complexType name="CadastralBlock">
    <xs:annotation>
        <xs:documentation>Cadastral quarter</xs:documentation>
    </xs:annotation>
    <xs:sequence>
        <xs:element name="number" type="xs:string">
            <xs:annotation>
                <xs:documentation>Cadastral number</xs:documentation>
            </xs:annotation>
        </xs:element>
</xs:complexType>

我们运行XJC像：

xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd

和GOT类等（吸气剂，setter和任何注释为了简化省略）：

public class CadastralBlock {
    protected String number;
}

但在我的情况下，我想知道如何类和字段在源文件被命名为！所以，这个插件做什么！

所以，你得到：

@XsdInfo(name = "Cadastral quarter", xsdElementPart = "<complexType name=\"CadastralBlock\">\n  <complexContent>\n    <restriction base=\"{http://www.w3.org/2001/XMLSchema}anyType\">\n      <sequence>\n        <element name=\"number\" type=\"{http://www.w3.org/2001/XMLSchema}string\"/></sequence>\n      </restriction>\n  </complexContent></complexType>")
public class CadastralBlock {
    @XsdInfo(name = "Cadastral number")
    protected String number;
}

如何使用

在命令行手动调用

如果你想运行它手动确保罐子类插件在运行类路径和只添加选项-XPluginDescriptionAnnotation。 F.e：

xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated -XPluginDescriptionAnnotation scheme.xsd

从Java / Groovy的呼叫

Driver.run(
    [
        '-XPluginDescriptionAnnotation'
        ,'-d', generatedClassesDir.absolutePath
        ,'-p', 'info.hubbitus.generated.test'
        ,'CadastralBlock.xsd'
    ] as String[]
    ,new XJCListener() {...}
)

请参阅例如测试XJCPluginDescriptionAnnotationTest。

从摇篮使用

使用 gradle这个-XJC-插件：

plugins {
    id 'java'
    id 'org.unbroken-dome.xjc' version '1.4.1' // https://github.com/unbroken-dome/gradle-xjc-plugin
}

...

dependencies {
    xjcClasspath 'info.hubbitus:xjc-documentation-annotation-plugin:1.0'
}

// Results by default in `build/xjc/generated-sources`
xjcGenerate {
    source = fileTree('src/main/resources') { include '*.xsd' }
    packageLevelAnnotations = false
    targetPackage = 'info.hubbitus.xjc.plugin.example'
    extraArgs = [ '-XPluginDescriptionAnnotation' ]
}

在示例项目完成gradle示例项目的-gradle 目录。