web-dev-qa-db-ja.com

生成されたクラスにXMLスキーマドキュメントからのJavadocを含める方法

私は現在、ほとんどのタイプと要素に<xsd:annotation>/<xsd:documentation>があるXMLスキーマを使用しています。このXMLスキーマからJava Beanを生成すると、それらのBeanのJavadocには、タイプ/要素の許可されたコンテンツに関する一般的な生成情報のみが含まれます。

関連する場所で<xsd:documentation>タグのコンテンツを確認したい（たとえば、complextTypeのそのタグのコンテンツは、そのcomplexTypeを表すために生成されたクラスのJavadocに表示される必要があります）。

これを達成する方法はありますか？

編集：このXMLスキーマはJAX-WSを使用するWSDLで使用されるため、このタグも適切な場合があります。

編集2：<jxb:javadoc>について読みました。私が理解していることから、別のJAXBバインディングファイルで、またはXMLスキーマで直接指定できます。それは私の問題をほぼ解決するでしょう。ただし、Javadocはドキュメントの主要なターゲットではないため、既存の<xsd:documentation>タグを使用したいと思います（これは主にデータ構造に関する情報であり、Javaそれと非JAXBツールが情報にアクセスできるようにします。<jxb:javadoc>とxsd:documentation>の両方でドキュメントを提供するのは間違っています。理由。

編集：Pascalの回答のおかげで、私はすでに半分の解決策があることに気付きました。complexTypesの<xsd:documentation>はJavadocの先頭に書き込まれています！問題は、まだonlyであり、complexTypesが使用され、simpleTypes（これもクラスになる可能性があります）と要素はJavadocなしです。

javajaxbjax-wsjavadocxjc
45
Joachim Sauer

通常の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からドキュメントを生成することができますが、これは質問に答えません.

36
Pascal Thivent

これは、JAXBリファレンス実装では不可能です。 XJCプラグインを作成しようとしても、プラグインAPIにはスキーマ定義への参照が与えられていないため、この情報を抽出する方法はありません。

私たちの唯一の希望は、JAXBの将来のバージョンで状況が修正されることです。 ここで機能リクエストを開く があります。

12
skaffman

次の手法は、JavaDocヘッダーをJava要素クラス（XMLスキーマから生成）に追加する場合に非常にうまく機能します。jax-b名前空間で定義されたタグにJavaDocをネストし、xml内にネストしますスキーマアノテーションとappinfoタグ。jaxb名前空間はドキュメントタグのタイプを定義することに注意してください。クラスタグとプロパティタグの2つを使用します。次の名前空間で定義されています：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>

このタグは型指定されていないリストを生成するため、ここで個々の選択肢を文書化しようとすると失敗します。

4
John Spragge