From 29fdb576abab5d4f5d90c10efd6f76f8fa20d457 Mon Sep 17 00:00:00 2001
From: Jose Luis Osorno <joseluis.osorno@ixxus.com>
Date: Fri, 11 Jan 2019 12:37:33 +0100
Subject: [PATCH] Fix javadoc errors

- Fix the javadoc error raised by the javadoc-maven-plugin.
- Configure the javadoc-maven-plugin to accept custom javadoc annotations
from maven mojo development.
---
 .../plugin/AbstractRefreshWebappMojo.java     |  4 ++
 .../maven/plugin/AbstractRunMojo.java         | 26 ++++++---
 .../alfresco/maven/plugin/InstallMojo.java    |  3 +-
 .../maven/plugin/IntegrationTestMojo.java     |  5 +-
 .../alfresco/maven/plugin/RefreshMojo.java    |  3 +-
 .../maven/plugin/RefreshRepoWebappMojo.java   |  3 +-
 .../maven/plugin/RefreshShareWebappMojo.java  |  3 +-
 .../alfresco/maven/plugin/VersionMojo.java    |  5 +-
 .../maven/plugin/archiver/AmpUnArchiver.java  |  2 +-
 .../maven/plugin/config/ModuleDependency.java |  9 ++--
 .../maven/plugin/config/TomcatDependency.java |  3 +-
 .../maven/plugin/config/TomcatWebapp.java     |  3 +-
 pom.xml                                       | 53 +++++++++++++++++++
 13 files changed, 99 insertions(+), 23 deletions(-)

diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/AbstractRefreshWebappMojo.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/AbstractRefreshWebappMojo.java
index bb236ef1..013c5f73 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/AbstractRefreshWebappMojo.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/AbstractRefreshWebappMojo.java
@@ -164,6 +164,8 @@ public abstract class AbstractRefreshWebappMojo extends AbstractMojo {
     /**
      * Perform a Refresh of Web Scripts container in webapp.
      * Called by specific refresh mojo implementation.
+     *
+     * @param url the relative path to refresh webscripts
      */
     protected void refreshWebScripts(String url) {
         // Create the Refresh URL for the Alfresco Tomcat server
@@ -184,6 +186,8 @@ public abstract class AbstractRefreshWebappMojo extends AbstractMojo {
     /**
      * Perform a Clear Dependency Caches call on Share webapp.
      * Called by specific refresh mojo implementation, currently only applicable to Share webapp.
+     *
+     * @param url the relative path to clear cache
      */
     protected void clearDependencyCaches(String url) {
         // Create the Clear Cache URL for the Alfresco Tomcat server
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/AbstractRunMojo.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/AbstractRunMojo.java
index 904a4c9a..e5152819 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/AbstractRunMojo.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/AbstractRunMojo.java
@@ -269,6 +269,8 @@ public abstract class AbstractRunMojo extends AbstractMojo {
     /**
      * Get the Tomcat port. By default the port is changed by using the maven.alfresco.tomcat.port property
      * but for legacy and external configuration purposes maven.tomcat.port will override if defined
+     *
+     * @return the Tomcat port
      */
     protected String getPort() {
         String port = tomcatPort;
@@ -281,7 +283,9 @@ public abstract class AbstractRunMojo extends AbstractMojo {
     }
 
     /**
+     * Check if Tomcat is already running.
      *
+     * @return <code>true</code> if Tomcat is already running, <code>false</code> otherwise
      */
     protected boolean tomcatIsRunning()  {
 
@@ -310,7 +314,7 @@ public abstract class AbstractRunMojo extends AbstractMojo {
      * Copy the alfresco-global.properties files. It contains database connection parameters and
      * other general configuration for Alfresco Repository (alfresco.war)
      *
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException when any problem appears copying the Alfresco global properties file
      */
     protected void copyAlfrescoGlobalProperties() throws MojoExecutionException {
         getLog().info("Copying and filtering alfresco-global.properties files to target/test-classes");
@@ -374,7 +378,7 @@ public abstract class AbstractRunMojo extends AbstractMojo {
      * Copy the Alfresco Enterprise license to its correct place in the Platform WAR, if it exists.
      * It is not enough to have it on the test classpath, then it will start up as Trial license...
      *
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException when any problem appears copying the Alfresco license
      */
     protected void copyAlfrescoLicense() throws MojoExecutionException {
 
@@ -411,7 +415,7 @@ public abstract class AbstractRunMojo extends AbstractMojo {
     /**
      * Copy Share Config Custom in order to have global overrides for development and dynamic port
      *
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException when any problem appears copying share config custom file
      */
     protected void copyShareConfigCustom() throws MojoExecutionException {
         final String warOutputDir = getWarOutputDir(SHARE_WAR_PREFIX_NAME);
@@ -452,7 +456,7 @@ public abstract class AbstractRunMojo extends AbstractMojo {
      * There is no custom classpath resolve mechanism for Share log4j,
      * to log custom stuff overriding standard log4j.properties is needed.
      *
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException when any problem appears copying the share log4j configuration
      */
     protected void copyShareLog4jConfig() throws MojoExecutionException {
         if (!useCustomShareLog4jConfig) {
@@ -492,7 +496,9 @@ public abstract class AbstractRunMojo extends AbstractMojo {
     /**
      * Copy and Build hotswap-agent.properties
      *
-     * @throws MojoExecutionException
+     * @param warPrefix path to the war root directory
+     *
+     * @throws MojoExecutionException when any problem appears copying hotswap agent properties
      */
     protected void copyHotswapAgentProperties(String warPrefix) throws MojoExecutionException {
         if ( copyHotswapAgentConfig == false ) {
@@ -526,6 +532,8 @@ public abstract class AbstractRunMojo extends AbstractMojo {
      * Build the customized Platform webapp (i.e. the Repository, alfresco.war)
      * that should be deployed by Tomcat by applying all AMPs and JARs from
      * the {@code <platformModules> } configuration.
+     *
+     * @throws MojoExecutionException when any problem appears building the platform war
      */
     protected void buildPlatformWar() throws MojoExecutionException {
         buildCustomWarInDir(PLATFORM_WAR_PREFIX_NAME, platformModules,
@@ -546,6 +554,8 @@ public abstract class AbstractRunMojo extends AbstractMojo {
      * Build the customized Share webapp (i.e. the share.war)
      * that should be deployed by Tomcat by applying all AMPs and JARs from
      * the {@code <shareModules> } configuration.
+     *
+     * @throws MojoExecutionException when any problem appears building the share war
      */
     protected void buildShareWar() throws MojoExecutionException {
         buildCustomWarInDir(SHARE_WAR_PREFIX_NAME, shareModules,
@@ -574,7 +584,7 @@ public abstract class AbstractRunMojo extends AbstractMojo {
      * @param originalWarGroupId    the Maven groupId for the original war file that should be customized
      * @param originalWarArtifactId the Maven artifactId for the original war file that should be customized
      * @param originalWarVersion    the Maven version for the original war file that should be customized
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException when any problem appears building the custom war
      */
     protected void buildCustomWarInDir(String warName,
                                        List<ModuleDependency> modules,
@@ -701,7 +711,7 @@ public abstract class AbstractRunMojo extends AbstractMojo {
      *
      * @param warName the name of the custom war
      * @return the customized war file artifactId, to be used by the tomcat7 plugin
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException when any problem appears packaging or installing the custom war
      */
     protected String packageAndInstallCustomWar(String warName) throws MojoExecutionException {
         final String warArtifactId = "${project.artifactId}-" + warName;
@@ -740,7 +750,7 @@ public abstract class AbstractRunMojo extends AbstractMojo {
      * configured in the SDK project.
      *
      * @param fork true if tomcat process should be forked
-     * @throws MojoExecutionException
+     * @throws MojoExecutionException when any problem appears starting tomcat
      */
     protected void startTomcat(boolean fork) throws MojoExecutionException {
         getLog().info("Starting Tomcat, fork = " + fork);
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/InstallMojo.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/InstallMojo.java
index b53e25a4..4ca97688 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/InstallMojo.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/InstallMojo.java
@@ -26,9 +26,10 @@ import org.apache.maven.plugin.MojoExecutionException;
 import org.apache.maven.plugin.MojoFailureException;
 
 /**
+ * <p>
  * Performs a AMP to WAR overlay invoking the Alfresco Repository ModuleManagementTool.
  * It therefore wraps and emulates the same WAR overlay performed by Alfresco MMT.
- * <p/>
+ * </p>
  * This goal will install the AMP file(s) found in ${ampLocation} onto the WAR (or exploded WAR) found in ${warLocation}
  * 
  * @version $Id:$
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/IntegrationTestMojo.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/IntegrationTestMojo.java
index c2b2a8fd..86e85a70 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/IntegrationTestMojo.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/IntegrationTestMojo.java
@@ -35,12 +35,13 @@ import java.util.Properties;
 import static org.twdata.maven.mojoexecutor.MojoExecutor.*;
 
 /**
+ * <p>
  * Alfresco Plugin mojo that are used when you want to run Integration Tests.
  * It will package up all the Integration Test classes and execute contained
  * tests with the Maven Failsafe plugin. The test classes will be added
  * to the platform war so they can be executed remotely via
- * the ${@link org.alfresco.rad.test.AlfrescoTestRunner}
- * <p/>
+ * the AlfrescoTestRunner.
+ * </p>
  * The Alfresco RAD module is also added to the Platform WAR so
  * the Alfresco Test runner classes are available.
  *
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshMojo.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshMojo.java
index 26427eb0..b0ff0ea8 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshMojo.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshMojo.java
@@ -21,11 +21,12 @@ import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 
 /**
+ * <p>
  * Refresh Alfresco Repo and Share Mojo.
  * Will refresh the Web Script container so new and changed
  * Spring Surf Web Scripts are detected.
  * Will also clear the dependency caches for web resources (CSS, JS, etc).
- * <p/>
+ * </p>
  * It is important to execute the refresh calls in the compile phase,
  * otherwise the files will be copied after this and the refresh calls
  * will not be recognized.
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshRepoWebappMojo.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshRepoWebappMojo.java
index c741c90a..9e38ab9b 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshRepoWebappMojo.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshRepoWebappMojo.java
@@ -21,10 +21,11 @@ import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 
 /**
+ * <p>
  * Refresh Alfresco Repository (alfresco.war) Mojo.
  * Will refresh the Web Script container so new and changed
  * Web Scripts are detected.
- * <p/>
+ * </p>
  * It is important to execute the refresh calls in the compile phase,
  * otherwise the files will be copied after this and the refresh calls
  * will not be recognized.
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshShareWebappMojo.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshShareWebappMojo.java
index 157e1898..30b40567 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshShareWebappMojo.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/RefreshShareWebappMojo.java
@@ -21,11 +21,12 @@ import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 
 /**
+ * <p>
  * Refresh Alfresco Share (share.war) Mojo.
  * Will refresh the Web Script container so new and changed
  * Spring Surf Web Scripts are detected.
  * Will also clear the dependency caches for web resources (CSS, JS, etc).
- * <p/>
+ * </p>
  * It is important to execute the refresh calls in the compile phase,
  * otherwise the files will be copied after this and the refresh calls
  * will not be recognized.
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/VersionMojo.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/VersionMojo.java
index 234d57fa..41d363c9 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/VersionMojo.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/VersionMojo.java
@@ -28,8 +28,7 @@ import org.apache.maven.project.MavenProject;
 
 /**
  * Removes -SNAPSHOT suffix from the version number (if present), optionally replacing it with a timestamp.
- * The result is provided in the Maven property ${noSnapshotVersion} (name can be changed using
- * <propertyName>myCustomVersion</>).
+ * The result is provided in the Maven property ${noSnapshotVersion}.
  * This feature is mostly needed to avoid Alfresco failing when installing AMP modules with non-numeric
  * versions.
  *
@@ -67,7 +66,7 @@ public class VersionMojo extends AbstractMojo {
     /**
      * Allows to append a custom (numeric) value to the current artifact's version,
      * i.e. appending the SCM build number can be accomplished defining
-     * <customVersionSuffix>${buildnumber}</customVersionSuffix> in the plugin
+     * &lt;customVersionSuffix&gt;${buildnumber}&lt;/customVersionSuffix&gt; in the plugin
      * configuration.
      *
      * @parameter property="maven.alfresco.customVersionSuffix"
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/archiver/AmpUnArchiver.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/archiver/AmpUnArchiver.java
index 58cdd1ec..8be254a3 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/archiver/AmpUnArchiver.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/archiver/AmpUnArchiver.java
@@ -14,7 +14,7 @@ import org.codehaus.plexus.component.annotations.Requirement;
 import org.codehaus.plexus.util.xml.Xpp3Dom;
 /**
  * This class provides AMP unpacking support for projects depending on AMPs
- * This allows for example AMPs to be specified as <overlay> in the maven-war-plugin
+ * This allows for example AMPs to be specified as &lt;overlay&gt; in the maven-war-plugin
  * @author mindthegab
  *
  */
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/ModuleDependency.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/ModuleDependency.java
index 7e2690e8..5d5d3f04 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/ModuleDependency.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/ModuleDependency.java
@@ -21,15 +21,18 @@ package org.alfresco.maven.plugin.config;
 import org.apache.commons.lang.StringUtils;
 
 /**
+ * <p>
  * Defines an Alfresco extension module dependency (JAR or AMP) to be
  * overlayed on an Alfresco webapp file.
- * <p/>
+ * </p>
+ * <p>
  * This is so we can skip the WAR projects in the AIO project,
  * and so we can include the Share Services AMP when running
  * with a simple platform JAR.
- * <p/>
+ * </p>
+ * <p>
  * This class is used by the RunMojo class.
- * <p/>
+ * </p>
  * Alfresco Maven Plugin config looks something like this:
  * <pre>
  *    {@code
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/TomcatDependency.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/TomcatDependency.java
index 7fcb5122..05c64429 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/TomcatDependency.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/TomcatDependency.java
@@ -19,8 +19,9 @@
 package org.alfresco.maven.plugin.config;
 
 /**
+ * <p>
  * Tomcat Dependency used in Embedded Tomcat Maven plugin configuration.
- * <p/>
+ * </p>
  * Alfresco Maven Plugin config looks something like this:
  * <pre>
  *    {@code
diff --git a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/TomcatWebapp.java b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/TomcatWebapp.java
index f4793300..f489bb9e 100644
--- a/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/TomcatWebapp.java
+++ b/plugins/alfresco-maven-plugin/src/main/java/org/alfresco/maven/plugin/config/TomcatWebapp.java
@@ -18,11 +18,12 @@
 package org.alfresco.maven.plugin.config;
 
 /**
+ * <p>
  * Tomcat Webapp used in Embedded Tomcat Maven plugin configuration.
  * These are custom webapps that you would want to include for some reason
  * (The {webapp artifact}.war need to be available in a Maven Repo).
  * Note. the standard webapps are included with plugin properties such as enablePlatform and enableShare.
- * <p/>
+ * </p>
  * Alfresco Maven Plugin config looks something like this:
  * <pre>
  *    {@code
diff --git a/pom.xml b/pom.xml
index c0df5b37..7823696b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -166,6 +166,59 @@
                         <skip>${skipTests}</skip>
                     </configuration>
                 </plugin>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-javadoc-plugin</artifactId>
+                    <configuration>
+                        <tags>
+                            <tag>
+                                <name>goal</name>
+                                <placement>a</placement>
+                                <head>Goal:</head>
+                            </tag>
+                            <tag>
+                                <name>requiresDependencyResolution</name>
+                                <placement>a</placement>
+                                <head>Requires Dependency Resolution:</head>
+                            </tag>
+                            <tag>
+                                <name>description</name>
+                                <placement>a</placement>
+                                <head>Description:</head>
+                            </tag>
+                            <tag>
+                                <name>phase</name>
+                                <placement>a</placement>
+                                <head>Phase:</head>
+                            </tag>
+                            <tag>
+                                <name>requiresProject</name>
+                                <placement>a</placement>
+                                <head>Requires Project:</head>
+                            </tag>
+                            <tag>
+                                <name>threadSafe</name>
+                                <placement>a</placement>
+                                <head>Thread-Safe:</head>
+                            </tag>
+                            <tag>
+                                <name>required</name>
+                                <placement>a</placement>
+                                <head>Required:</head>
+                            </tag>
+                            <tag>
+                                <name>readonly</name>
+                                <placement>a</placement>
+                                <head>Read only:</head>
+                            </tag>
+                            <tag>
+                                <name>parameter</name>
+                                <placement>a</placement>
+                                <head>Parameter:</head>
+                            </tag>
+                        </tags>
+                    </configuration>
+                </plugin>
             </plugins>
         </pluginManagement>
         <extensions>