Generate documentation from modello model

mojohaus · Jul 2, 2024 · 31bf683 · 31bf683
1 parent 2a72bd0
commit 31bf683
Show file tree

Hide file tree

Showing 6 changed files with 38 additions and 13 deletions.
diff --git a/pom.xml b/pom.xml
@@ -308,7 +308,6 @@
               <goal>xsd</goal>
               <goal>xpp3-writer</goal>
             </goals>
-            <phase>generate-sources</phase>
             <configuration>
               <version>1.0.0</version>
               <models>
@@ -322,14 +321,27 @@
               <goal>java</goal>
               <goal>xsd</goal>
             </goals>
-            <phase>generate-sources</phase>
             <configuration>
               <version>1.0.0</version>
               <models>
                 <model>src/main/mdo/TagListOptions.mdo</model>
               </models>
             </configuration>
           </execution>
+          <execution>
+            <id>modello-docs</id>
+            <goals>
+              <goal>xdoc</goal>
+            </goals>
+            <phase>pre-site</phase>
+            <configuration>
+              <version>1.0.0</version>
+              <models>
+                <model>src/main/mdo/TagListOutput.mdo</model>
+                <model>src/main/mdo/TagListOptions.mdo</model>
+              </models>
+            </configuration>
+          </execution>
         </executions>
       </plugin>
     </plugins>

diff --git a/src/main/java/org/codehaus/mojo/taglist/TagListReport.java b/src/main/java/org/codehaus/mojo/taglist/TagListReport.java
@@ -92,7 +92,9 @@ public class TagListReport extends AbstractMavenReport {
     private String[] excludes;
 
     /**
-     * Specifies the directory where the xml output will be generated.
+     * Specifies the directory where the xml {@code taglist.xml} output will be generated.
+     * <br>
+     * The xml report has a <a href="taglistOutput.html">format</a>.
      *
      * @since 2.3
      */
@@ -184,6 +186,7 @@ public class TagListReport extends AbstractMavenReport {
      * <br/>
      * <br/>
      * For complete examples see the <a href="usage.html"><b>Usage</b></a> page. <br/>
+     * Type description <a href="taglistOptions.html"><b>taglistOptions</b></a>
      *
      * @since 2.4
      */

diff --git a/src/main/mdo/TagListOptions.mdo b/src/main/mdo/TagListOptions.mdo
@@ -17,7 +17,10 @@ KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
-<model xsd.namespace="http://modello.codehaus.org/MODELLO/1.0.0" xml.schemaLocation="http://modello.codehaus.org/xsd/modello-1.0.0.xsd" xml.namespace="org.codehaus.mojo.taglist-maven-plugin" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://modello.codehaus.org/MODELLO/1.0.0 http://modello.codehaus.org/xsd/modello-1.0.0.xsd" xmlns="http://modello.codehaus.org/MODELLO/1.0.0">
+<model xmlns="http://codehaus-plexus.github.io/MODELLO/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+			 xsi:schemaLocation="http://codehaus-plexus.github.io/MODELLO/2.0.0 https://codehaus-plexus.github.io/modello/xsd/modello-2.0.0.xsd"
+			 xml.namespace="https://www.mojohaus.org/TAGLISTOPTIONS/${version}"
+			 xml.schemaLocation="https://www.mojohaus.org/taglist-maven-plugin/xsd/taglistOptions-${version}.xsd">
 	<id>taglistOptions</id>
 	<name>taglistOptions</name>
 	<description><![CDATA[Model for TagList Options.]]></description>
@@ -81,9 +84,10 @@ under the License.
 				<field>
 					<name>matchType</name>
 					<required>false</required>
-					<description><![CDATA[The type of comparison to perform on the string.  Options:  exact, ignoreCase, regEx   Default = exact.]]></description>
+					<description><![CDATA[The type of comparison to perform on the string.  Options:  exact, ignoreCase, regEx.]]></description>
 					<version>1.0.0</version>
 					<type>String</type>
+					<defaultValue>exact</defaultValue>
 				</field>
 			</fields>
 		</class>

diff --git a/src/main/mdo/TagListOutput.mdo b/src/main/mdo/TagListOutput.mdo
@@ -17,8 +17,11 @@ KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
-<model xml.namespace="org.codehaus.mojo.taglist-maven-plugin">
-  <id>TaglistOutput</id>
+<model xmlns="http://codehaus-plexus.github.io/MODELLO/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:schemaLocation="http://codehaus-plexus.github.io/MODELLO/2.0.0 https://codehaus-plexus.github.io/modello/xsd/modello-2.0.0.xsd"
+       xml.namespace="https://www.mojohaus.org/TAGLISTOUTPUT/${version}"
+       xml.schemaLocation="https://www.mojohaus.org/taglist-maven-plugin/xsd/taglistOutput-${version}.xsd">
+  <id>taglistOutput</id>
   <name>TaglistOutput</name>
   <description><![CDATA[Model for TagList XML output.]]></description>
   <defaults>
@@ -37,7 +40,7 @@ under the License.
         <field>
           <name>tags</name>
           <version>1.0.0</version>
-          <association xml.associationTagName="tag">
+          <association xml.tagName="tag">
             <type>TagListXMLTag</type>
             <multiplicity>*</multiplicity>
           </association>
@@ -67,7 +70,7 @@ under the License.
           <name>files</name>
           <version>1.0.0</version>
           <required>true</required>
-          <association xml.associationTagName="file">
+          <association xml.tagName="file">
             <type>TagListXMLFile</type>
             <multiplicity>*</multiplicity>
           </association>
@@ -95,7 +98,7 @@ under the License.
         <field>
           <name>comments</name>
           <version>1.0.0</version>
-          <association xml.associationTagName="comment">
+          <association xml.tagName="comment">
             <type>TagListXMLComment</type>
             <multiplicity>*</multiplicity>
           </association>

diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm
@@ -4,7 +4,6 @@
  Fabrice Bellingard
  ------
 
-
 Usage
 
 *Available Configuration Options
@@ -38,7 +37,7 @@ Usage
 
   NOTE: 
   If you like having cross references included you need to define the 
-  taglist-maven-plugin after {{{http://maven.apache.org/jxr/maven-jxr-plugin/}maven-jxr-plugin}} 
+  taglist-maven-plugin after {{{https://maven.apache.org/jxr/maven-jxr-plugin/}maven-jxr-plugin}}
   otherwise you will get a warning (See also {{{./faq.html}FAQ}}).
 
   The report will be generated when executing the <<<site>>> life cycle phase,
@@ -89,3 +88,5 @@ mvn site
   ...
 </project>
 +---+
+
+  See also type description {{{./taglistOptions.html}taglistOptions}}.
diff --git a/src/test/resources/unit/basic-config-test/expected-taglist.xml b/src/test/resources/unit/basic-config-test/expected-taglist.xml
@@ -1,5 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<report xmlns="org.codehaus.mojo.taglist-maven-plugin">
+<report xsi:schemaLocation="https://www.mojohaus.org/TAGLISTOUTPUT/1.0.0 https://www.mojohaus.org/taglist-maven-plugin/xsd/taglistOutput-1.0.0.xsd"
+        xmlns="https://www.mojohaus.org/TAGLISTOUTPUT/1.0.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <tags>
     <tag name="@create_output" count="1">
       <files>