Cách tạo các lớp được tạo có chứa Javadoc từ tài liệu Lược đồ XML

Question

Tôi hiện đang làm việc với một Lược đồ XML có <xsd:annotation>/<xsd:documentation> trên hầu hết các loại và các thành phần. Khi tôi tạo ra Java Beans từ lược đồ XML này, thì Javadoc của những Beans này chỉ chứa một số thông tin được tạo chung chung về nội dung được cho phép của kiểu/phần tử.

Tôi muốn xem nội dung của thẻ <xsd:documentation> ở các vị trí có liên quan (ví dụ: nội dung của thẻ đó cho một complextType sẽ hiển thị trong Javadoc của lớp được tạo để đại diện cho complexType đó).

Có cách nào để đạt được điều này không?

Chỉnh sửa: Lược đồ XML này sẽ được sử dụng trong WSDL với JAX-WS, vì vậy thẻ này cũng có thể thích hợp.

Chỉnh sửa 2: Tôi đã đọc khoảng <jxb:javadoc>. Từ những gì tôi hiểu tôi có thể chỉ định rằng trong một tệp JAXB ràng buộc riêng biệt hoặc trực tiếp trong Lược đồ XML. Điều đó gần như sẽ giải quyết vấn đề của tôi. Nhưng tôi muốn sử dụng thẻ <xsd:documentation> hiện có, vì Javadoc không phải là mục tiêu chính của tài liệu (thông tin về cấu trúc dữ liệu chủ yếu và không phải về Hạt Java được tạo ra từ nó) và cho phép các công cụ không phải JAXB truy cập thông tin cũng. Cung cấp tài liệu ở cả hai số <jxb:javadoc> và xsd:documentation> "cảm thấy" sai, vì tôi đang sao chép dữ liệu (và công việc) không có lý do chính đáng.

Sửa 3: Cảm ơn câu trả lời của Pascal Tôi nhận ra rằng tôi đã có một nửa giải pháp: Các <xsd:documentation> của complexType s được ghi vào đầu Javadoc của nó! Vấn đề vẫn là chỉ rằng complexType s được sử dụng và simpleType s (điều này cũng có thể dẫn đến một lớp) và các yếu tố vẫn còn kém hơn Javadoc.

Answer 1

Tôi chưa bao giờ có thể nhận được thông thường xsd:documentation để được đặt trong nguồn java ngoại trừ nếu và chỉ khi đó là Loại phức hợp. Tài liệu cho các phần tử, các loại đơn giản, v.v. bị bỏ qua.

Vì vậy, tôi sẽ chỉ sử dụng jxb:javadoc. Để làm như vậy, hãy bao gồm định nghĩa của xmlns:jxb="http://java.sun.com/xml/ns/jaxb" trong phần tử <xsd:schema> của bạn.

Thêm một đứa trẻ để <xsd:complexType> hoặc <xsd: element> hoặc <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> 

đâu XXX là một trong hai "lớp" hay "tài sản".

Đối với một gói phần mềm bạn viết một đứa trẻ để 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> 

tài liệu

Viết HTML đòi hỏi bracketing với <![CDATA[ --- ]]>

(EDIT: Trong khi viết câu trả lời của tôi, câu hỏi đã được chỉnh sửa bởi OP vì vậy tôi m cập nhật nó cho phù hợp)

Trong trường hợp của tôi, javadoc là mục tiêu duy nhất để có thể chấp nhận sử dụng jxb:javadoc. Nhưng bản cập nhật của bạn có ý nghĩa hoàn hảo và, thực ra, tôi hoàn toàn đồng ý với bạn.Đáng buồn thay, tôi không bao giờ tìm thấy một giải pháp lý tưởng cho tình huống bạn mô tả (vì vậy tôi sẽ làm theo câu hỏi này rất cẩn thận). Có thể bạn có thể sử dụng một cái gì đó như xframe để tạo tài liệu từ xsd:documentation, nhưng điều này không trả lời được câu hỏi.

Answer 2

Điều này không thể thực hiện được với việc triển khai tham chiếu JAXB. Thậm chí nếu bạn cố gắng viết một plugin XJC, bạn sẽ thấy rằng API plugin không được tham chiếu đến định nghĩa lược đồ, do đó không có cách nào để trích xuất thông tin này.

Hy vọng duy nhất của chúng tôi là phiên bản tương lai của JAXB sẽ khắc phục tình huống. Có một số open feature request here.

Answer 3

Tôi thấy các kỹ thuật sau hoạt động khá tốt để thêm các tiêu đề JavaDoc vào các lớp phần tử Java (được tạo từ các lược đồ XML). Tôi lồng JavaDoc trong các thẻ được định nghĩa trong không gian tên jax-b, lồng trong chú thích lược đồ xml và thẻ appinfo. Lưu ý không gian tên jaxb định nghĩa các loại thẻ tài liệu; Tôi sử dụng hai trong số đó: các lớp và các thẻ thuộc tính. được định nghĩa trong không gian tên sau: xmlns: jxb = "http://java.sun.com/xml/ns/jaxb"

1) Để ghi lại một lớp, tôi sử dụng thẻ "class" jaxb theo trình tự sau :

<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) để ghi lại một yếu tố, tôi sử dụng "tài sản" tag như sau:

 <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) tôi sử dụng cùng một bộ thẻ để ghi lại các thuộc tính:

 <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) Để ghi lại lựa chọn, tôi sử dụng thẻ jaxb thuộc tính và tôi ghi lại lựa chọn.

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

Cố gắng ghi lại những lựa chọn cá nhân ở đây sẽ thất bại, vì thẻ này tạo ra một danh sách không định kiểu.