[MJAVADOC-453] Using Alternate Doclet documentation example snippet i…

…s out of date and does not work

pom.xml

@@ -475,6 +475,9 @@ under the License.
               <localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>
               <projectsDirectory>src/it/projects</projectsDirectory>
               <settingsFile>src/it/mrm/settings.xml</settingsFile>
+              <pomIncludes combine.children="append">
+                <pomInclude>examples/*/pom.xml</pomInclude>
+              </pomIncludes>
               <pomExcludes>
                 <pomExclude>MJAVADOC-181/pom.xml</pomExclude> <!-- seems to be wrong, see comment in Jira issue  -->
                 <pomExclude>output-encoding/pom.xml</pomExclude>

src/it/projects/examples/alternate-doclet/invoker.properties

@@ -0,0 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# this plugins expects tools.jar, hence Java 8 or before
+invoker.java.version=9-
+invoker.goals=javadoc:javadoc

src/it/projects/examples/alternate-doclet/pom.xml

@@ -0,0 +1,56 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>org.apache.maven.plugins.javadoc.example</groupId>
+  <artifactId>alternate-doclet</artifactId>
+  <version>1.0.0-SNAPSHOT</version>
+
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <maven.compiler.source>@maven.compiler.source@</maven.compiler.source>
+    <maven.compiler.target>@maven.compiler.target@</maven.compiler.target>
+  </properties>
+
+  <url>http://maven.apache.org/plugins/maven-javadoc-plugin/examples/alternate-doclet.html</url>
+
+  <build>
+    <plugins>
+      <!-- START SNIPPET: umlgraph -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>@project.version@</version>
+        <configuration>
+          <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
+          <docletArtifact>
+            <!-- UMLGraph cannot be used with Java 9 or above due to substantial changes in the JavaDoc Doclet API-->
+            <groupId>org.umlgraph</groupId>
+            <artifactId>umlgraph</artifactId>
+            <version>5.6.6</version>
+          </docletArtifact>
+          <additionalparam>-views</additionalparam>
+        </configuration>
+      </plugin>
+      <!-- END SNIPPET: umlgraph -->
+    </plugins>
+  </build>
+</project>

src/it/projects/examples/alternate-doclet/src/main/java/com/example/Foo.java

@@ -0,0 +1,31 @@
+package com.example;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * This is a Foo.
+ */
+public interface Foo
+{
+    /**
+     * Frobnicates the foo.
+     */
+    public void frobnicate();
+}

src/it/projects/examples/alternate-doclet/verify.groovy

@@ -0,0 +1,24 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+File options = new File( basedir, 'target/site/apidocs/options' )
+
+assert options.text.readLines().dropWhile{it != '-doclet'}.get(1) == "'org.umlgraph.doclet.UmlGraphDoc'"
+assert options.text.readLines().dropWhile{it != '-docletpath'}.get(1).contains('org/umlgraph/umlgraph/5.6.6/umlgraph-5.6.6.jar')
+

src/site/apt/examples/alternate-doclet.apt.vm

@@ -37,35 +37,7 @@ Using Alternate Doclet
  <<Note about UmlGraph>>: You must have the Graphviz binary in your PATH, or the images will not be generated.
  For more information about Graphviz, please refer to {{http://www.graphviz.org/}}.
 
-+-----+
-<project>
-  ...
-  <reporting> (or <build>)
-    <plugins>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-javadoc-plugin</artifactId>
-        <version>${project.version}</version>
-        <configuration>
-          <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
-
-          <!-- <docletPath>/path/to/UmlGraph.jar</docletPath> -->
-          <docletArtifact>
-            <groupId>org.umlgraph</groupId>
-            <artifactId>doclet</artifactId>
-            <version>5.1</version>
-          </docletArtifact>
-          <additionalOptions>
-            <additionalOption>-views</additionalOption>
-          </additionalOptions>
-        </configuration>
-      </plugin>
-    ...
-    </plugins>
-  </reporting> (or </build>)
-  ...
-</project>
-+-----+
+%{snippet|id=umlgraph|file=target/it/examples/alternate-doclet/pom.xml}
 
  <<Note>>: