You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by rf...@apache.org on 2021/05/16 13:14:51 UTC
[maven-javadoc-plugin] 01/01: [MJAVADOC-453] Using Alternate Doclet
documentation example snippet is out of date and does not work
This is an automated email from the ASF dual-hosted git repository.
rfscholte pushed a commit to branch MJAVADOC-453
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
commit e9729cecf01bd1962b5fd4cbff14996bad8f92a6
Author: rfscholte <rf...@apache.org>
AuthorDate: Sun May 16 15:14:36 2021 +0200
[MJAVADOC-453] Using Alternate Doclet documentation example snippet is out of date and does not work
---
pom.xml | 3 ++
.../examples/alternate-doclet/invoker.properties | 20 ++++++++
src/it/projects/examples/alternate-doclet/pom.xml | 56 ++++++++++++++++++++++
.../src/main/java/com/example/Foo.java | 31 ++++++++++++
.../examples/alternate-doclet/verify.groovy | 24 ++++++++++
src/site/apt/examples/alternate-doclet.apt.vm | 30 +-----------
6 files changed, 135 insertions(+), 29 deletions(-)
diff --git a/pom.xml b/pom.xml
index a4af532..6aec98e 100644
--- a/pom.xml
+++ b/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>
diff --git a/src/it/projects/examples/alternate-doclet/invoker.properties b/src/it/projects/examples/alternate-doclet/invoker.properties
new file mode 100644
index 0000000..026438d
--- /dev/null
+++ b/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
diff --git a/src/it/projects/examples/alternate-doclet/pom.xml b/src/it/projects/examples/alternate-doclet/pom.xml
new file mode 100644
index 0000000..c477ce0
--- /dev/null
+++ b/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>
diff --git a/src/it/projects/examples/alternate-doclet/src/main/java/com/example/Foo.java b/src/it/projects/examples/alternate-doclet/src/main/java/com/example/Foo.java
new file mode 100644
index 0000000..b1a91fa
--- /dev/null
+++ b/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();
+}
diff --git a/src/it/projects/examples/alternate-doclet/verify.groovy b/src/it/projects/examples/alternate-doclet/verify.groovy
new file mode 100644
index 0000000..c16fc76
--- /dev/null
+++ b/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')
+
diff --git a/src/site/apt/examples/alternate-doclet.apt.vm b/src/site/apt/examples/alternate-doclet.apt.vm
index 04cbbbc..be1f798 100644
--- a/src/site/apt/examples/alternate-doclet.apt.vm
+++ b/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>>: