كيفية جعل الفئات التي تم إنشاؤها تحتوي على Javadoc من وثائق مخطط XML

Question

أنا أعمل حاليًا مع مخطط XML الذي يحتوي على <xsd:annotation>/<xsd:documentation> على معظم الأنواع والعناصر.عندما أقوم بإنشاء Java Beans من مخطط XML هذا، فإن Javadoc الخاص بهذه Beans يحتوي فقط على بعض المعلومات العامة التي تم إنشاؤها حول المحتوى المسموح به للنوع/العنصر.

أود أن أرى محتوى <xsd:documentation> علامة في الأماكن ذات الصلة (على سبيل المثال، يجب أن يظهر محتوى تلك العلامة الخاصة بنوع complextType في Javadoc للفئة التي تم إنشاؤها لتمثيل هذا النوع المعقد).

هل هناك أي طريقة لتحقيق ذلك؟

يحرر:سيتم استخدام مخطط XML هذا في WSDL مع JAX-WS، لذلك قد تكون هذه العلامة مناسبة أيضًا.

تحرير 2:لقد قرأت عن <jxb:javadoc>.مما أفهمه يمكنني تحديد ذلك إما في ملف ربط JAXB منفصل أو مباشرة في مخطط XML.وهذا من شأنه أن يحل مشكلتي تقريبا.لكني أفضل استخدام الموجود <xsd:documentation> العلامة، نظرًا لأن Javadoc ليس الهدف الأساسي للوثائق (إنها معلومات حول بنية البيانات بشكل أساسي وليس حول Java Beans التي تم إنشاؤها منها) وللسماح للأدوات غير التابعة لـ JAXB بالوصول إلى المعلومات أيضًا.توفير الوثائق في كليهما <jxb:javadoc> و xsd:documentation> "أشعر" بالخطأ، لأنني أقوم بتكرار البيانات (والعمل) دون سبب وجيه.

تحرير 3:بفضل إجابة باسكال أدركت أن لدي نصف الحل بالفعل:ال <xsd:documentation> ل complexTypeتمت كتابة s في بداية Javadoc!المشكلة لا تزال هي ذلك فقط الذي - التي complexTypeيتم استخدام s و simpleTypes (والذي يمكن أن يؤدي أيضًا إلى فئة) ولا تزال العناصر أقل من Javadoc.

Answer 1

لم أتمكن أبدًا من الحصول على انتظام xsd:documentation ليتم وضعها في مصدر جافا باستثناء إذا وفقط إذا لقد كان نوعًا معقدًا.يتم تجاهل وثائق العناصر ، والأنواع البسيطة ، وما إلى ذلك.

لذلك انتهى بي الأمر باستخدام 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

وأجد الأساليب التالية تعمل بشكل جيد جدا لإضافة رؤوس جافادوك إلى الطبقات عنصر جافا (ولدت من مخططات XML). I عش جافادوك في العلامات المحددة في JAX-ب مساحة الاسم، متداخلة ضمن الشرح أكس المخطط وappinfo العلامات. لاحظ مساحة JAXB يحدد أنواع علامات التوثيق؛ يمكنني استخدام اثنين من هناك: الطبقة والعلامات الممتلكات. المعرفة في ما يلي مساحة الاسم: XMLNS: jxb = "http://java.sun.com/xml/ns/jaxb"

1) توثيق فئة، وأنا استخدم 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-documentation-annotation-plugin.

ماذا يفعل: <annotation><documentation> -> التعليقات التوضيحية لفئة جافا

وقال لدينا هذا الكائن الموصوف في 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

وحصلت على فئة مثل (getters، setters وأي تعليقات توضيحية محذوفة من أجل البساطة):

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

كيف تستعمل

الاتصال اليدوي في سطر الأوامر

إذا كنت تريد تشغيله يدويًا، فتأكد من وجود فئة jar مع البرنامج المساعد في run classpath وأضف الخيار فقط -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

مع gradle-xjc-plugin:

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 دليل المشروع.