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 <[email protected]> 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>>:
