464727 - Update Javadoc for Java 8 DocLint

2015-04-22 17:18:05 -07:00 · 2015-04-22 17:18:05 -07:00 · 6ecfb96508
parent 4db2784354
commit 6ecfb96508
15 changed files with 83 additions and 55 deletions
--- a/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/AppLifeCycle.java
+++ b/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/AppLifeCycle.java
@ -32,11 +32,11 @@ import org.eclipse.jetty.util.log.Logger;

 /**
 * The lifecycle of an App in the {@link DeploymentManager}.
- * 
+ * <p>
 * Setups a the default {@link Graph}, and manages the bindings to the life cycle via the {@link AppLifeCycle.Binding}
 * annotation.
 * <p>
- * <img src="doc-files/AppLifeCycle.png">
+ * <img alt="app lifecycle graph" src="doc-files/AppLifeCycle.png">
 */
 public class AppLifeCycle extends Graph
 {
--- a/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/AppProvider.java
+++ b/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/AppProvider.java
@ -31,7 +31,7 @@ public interface AppProvider extends LifeCycle
    /**
     * Set the Deployment Manager
     * 
-     * @param deploymentManager
+     * @param deploymentManager the deployment manager
     * @throws IllegalStateException
     *             if the provider {@link #isRunning()}.
     */
@ -41,8 +41,8 @@ public interface AppProvider extends LifeCycle
    /** Create a ContextHandler for an App
     * @param app The App
     * @return A ContextHandler
-     * @throws IOException
-     * @throws Exception 
+     * @throws IOException if unable to create context
+     * @throws Exception if unable to create context
     */
    ContextHandler createContextHandler(App app) throws Exception;
 }
--- a/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/DeploymentManager.java
+++ b/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/DeploymentManager.java
@ -51,14 +51,14 @@ import org.eclipse.jetty.util.log.Logger;
 * <p>
 * Responsibilities:
 * <p>
- * <img src="doc-files/DeploymentManager_Roles.png">
+ * <img alt="deployment manager roles graph" src="doc-files/DeploymentManager_Roles.png">
 * <ol>
 * <li>Tracking Apps and their LifeCycle Location</li>
 * <li>Managing AppProviders and the Apps that they provide.</li>
 * <li>Executing AppLifeCycle on App based on current and desired LifeCycle Location.</li>
 * </ol>
 * <p>
- * <img src="doc-files/DeploymentManager.png">
+ * <img alt="deployment manager graph" src="doc-files/DeploymentManager.png">
 */
@ManagedObject("Deployment Manager")
 public class DeploymentManager extends ContainerLifeCycle
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/JaspiAuthenticatorFactory.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/JaspiAuthenticatorFactory.java
@ -135,6 +135,8 @@ public class JaspiAuthenticatorFactory extends DefaultAuthenticatorFactory
     * If {@link #setServiceSubject(Subject)} has not been used to 
     * set a subject, then the {@link Server#getBeans(Class)} method is
     * used to look for a Subject.
+     * @param server the server to pull the Subject from
+     * @return the subject
     */
    protected Subject findServiceSubject(Server server)
    {
@ -151,6 +153,9 @@ public class JaspiAuthenticatorFactory extends DefaultAuthenticatorFactory
     * If {@link #setServerName(String)} has not been called, then
     * use the name of the a principal in the service subject.
     * If not found, return "server".
+     * @param server not used
+     * @param subject the subject to use
+     * @return the server name from the subject (or default value if not found in subject or principals)
     */
    protected String findServerName(Server server, Subject subject)
    {
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/JaspiMessageInfo.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/JaspiMessageInfo.java
@ -27,11 +27,8 @@ import javax.security.auth.message.MessageInfo;
 import javax.servlet.ServletRequest;
 import javax.servlet.ServletResponse;

-
 /**
 * Almost an implementation of jaspi MessageInfo.
- *
- * @version $Rev: 4660 $ $Date: 2009-02-25 17:29:53 +0100 (Wed, 25 Feb 2009) $
 */
 public class JaspiMessageInfo implements MessageInfo
 {
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/ServletCallbackHandler.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/ServletCallbackHandler.java
@ -39,10 +39,7 @@ import org.eclipse.jetty.security.jaspi.callback.CredentialValidationCallback;
 import org.eclipse.jetty.server.UserIdentity;

 /**
- * 
 * Idiot class required by jaspi stupidity
- * 
- * @version $Rev: 4793 $ $Date: 2009-03-19 00:00:01 +0100 (Thu, 19 Mar 2009) $
 */
 public class ServletCallbackHandler implements CallbackHandler
 {
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/SimpleAuthConfig.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/SimpleAuthConfig.java
@ -26,9 +26,6 @@ import javax.security.auth.message.MessageInfo;
 import javax.security.auth.message.config.ServerAuthConfig;
 import javax.security.auth.message.config.ServerAuthContext;

-/**
- * @version $Rev: 4660 $ $Date: 2009-02-25 17:29:53 +0100 (Wed, 25 Feb 2009) $
- */
 public class SimpleAuthConfig implements ServerAuthConfig
 {
    public static final String HTTP_SERVLET = "HttpServlet";
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/BaseAuthModule.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/BaseAuthModule.java
@ -45,9 +45,6 @@ import org.eclipse.jetty.util.B64Code;
 import org.eclipse.jetty.util.security.Credential;
 import org.eclipse.jetty.util.security.Password;

-/**
- * @version $Rev: 4792 $ $Date: 2009-03-18 22:55:52 +0100 (Wed, 18 Mar 2009) $
- */
 public class BaseAuthModule implements ServerAuthModule, ServerAuthContext
 {
    private static final Class[] SUPPORTED_MESSAGE_TYPES = new Class[] { HttpServletRequest.class, HttpServletResponse.class };
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/BasicAuthModule.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/BasicAuthModule.java
@ -36,10 +36,7 @@ import org.eclipse.jetty.util.log.Log;
 import org.eclipse.jetty.util.log.Logger;
 import org.eclipse.jetty.util.security.Constraint;

-/**
- * @deprecated use *ServerAuthentication
- * @version $Rev: 4660 $ $Date: 2009-02-25 17:29:53 +0100 (Wed, 25 Feb 2009) $
- */
+@Deprecated
 public class BasicAuthModule extends BaseAuthModule
 {
    private static final Logger LOG = Log.getLogger(BasicAuthModule.class);
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/ClientCertAuthModule.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/ClientCertAuthModule.java
@ -34,10 +34,7 @@ import org.eclipse.jetty.util.B64Code;
 import org.eclipse.jetty.util.security.Constraint;
 import org.eclipse.jetty.util.security.Password;

-/**
- * @deprecated use *ServerAuthentication
- * @version $Rev: 4530 $ $Date: 2009-02-13 00:47:44 +0100 (Fri, 13 Feb 2009) $
- */
+@Deprecated
 public class ClientCertAuthModule extends BaseAuthModule
 {

--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/DigestAuthModule.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/DigestAuthModule.java
@ -42,15 +42,11 @@ import org.eclipse.jetty.util.log.Logger;
 import org.eclipse.jetty.util.security.Constraint;
 import org.eclipse.jetty.util.security.Credential;

-/**
- * @deprecated use *ServerAuthentication
- * @version $Rev: 4627 $ $Date: 2009-02-20 00:07:19 +0100 (Fri, 20 Feb 2009) $
- */
+@Deprecated
 public class DigestAuthModule extends BaseAuthModule
 {
    private static final Logger LOG = Log.getLogger(DigestAuthModule.class);

-
    protected long maxNonceAge = 0;

    protected long nonceSecret = this.hashCode() ^ System.currentTimeMillis();
@ -213,11 +209,10 @@ public class DigestAuthModule extends BaseAuthModule
    }

    /**
-     * @param nonce
+     * @param nonce the nonce
     * @param timestamp should be timestamp of request.
     * @return -1 for a bad nonce, 0 for a stale none, 1 for a good nonce
     */
-    /* ------------------------------------------------------------ */
    public int checkNonce(String nonce, long timestamp)
    {
        try
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/FormAuthModule.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/FormAuthModule.java
@ -44,10 +44,7 @@ import org.eclipse.jetty.util.log.Logger;
 import org.eclipse.jetty.util.security.Constraint;
 import org.eclipse.jetty.util.security.Password;

-/**
- * @deprecated use *ServerAuthentication
- * @version $Rev: 4792 $ $Date: 2009-03-18 22:55:52 +0100 (Wed, 18 Mar 2009) $
- */
+@Deprecated
 public class FormAuthModule extends BaseAuthModule
 {
    private static final Logger LOG = Log.getLogger(FormAuthModule.class);
--- a/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/UserInfo.java
+++ b/jetty-jaspi/src/main/java/org/eclipse/jetty/security/jaspi/modules/UserInfo.java
@ -20,9 +20,6 @@ package org.eclipse.jetty.security.jaspi.modules;

 import java.util.Arrays;

-/**
- * @version $Rev: 4466 $ $Date: 2009-02-10 23:42:54 +0100 (Tue, 10 Feb 2009) $
- */
 public class UserInfo
 {
    private final String userName;
--- a/jetty-jspc-maven-plugin/pom.xml
+++ b/jetty-jspc-maven-plugin/pom.xml
@ -14,25 +14,85 @@
  <build>
    <plugins>
      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <skip>true</skip>
        </configuration>
      </plugin>
      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-plugin-plugin</artifactId>
-        <version>2.9</version>
+        <version>3.4</version>
        <executions>
          <execution>
            <id>exec-plugin-doc</id>
            <phase>generate-sources</phase>
            <goals>
-              <goal>xdoc</goal>
+              <goal>descriptor</goal>
              <goal>helpmojo</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <configuration>
+          <tags>
+            <tag>
+              <name>phase</name>
+              <placement>t</placement>
+              <head>Phase:</head>
+            </tag>
+            <tag>
+              <name>goal</name>
+              <placement>t</placement>
+              <head>Goal:</head>
+            </tag>
+            <tag>
+              <name>description</name>
+              <placement>a</placement>
+              <head>Description:</head>
+            </tag>
+            <tag>
+              <name>parameter</name>
+              <placement>f</placement>
+              <head>Parameter:</head>
+            </tag>
+            <tag>
+              <name>required</name>
+              <placement>f</placement>
+              <head>Required:</head>
+            </tag>
+            <tag>
+              <name>readonly</name>
+              <placement>f</placement>
+              <head>Read-Only:</head>
+            </tag>
+            <tag>
+              <name>execute</name>
+              <placement>X</placement>
+              <head />
+            </tag>
+            <tag>
+              <name>requiresDependencyResolution</name>
+              <placement>X</placement>
+              <head />
+            </tag>
+            <tag>
+              <name>requiresProject</name>
+              <placement>X</placement>
+              <head />
+            </tag>
+            <tag>
+              <name>threadSafe</name>
+              <placement>X</placement>
+              <head />
+            </tag>
+          </tags>
+        </configuration>
+      </plugin>
    </plugins>
  </build>
  <dependencies>
--- a/jetty-jspc-maven-plugin/src/main/java/org/eclipse/jetty/jspc/plugin/JspcMojo.java
+++ b/jetty-jspc-maven-plugin/src/main/java/org/eclipse/jetty/jspc/plugin/JspcMojo.java
@ -51,29 +51,21 @@ import org.eclipse.jetty.util.PatternMatcher;
 import org.eclipse.jetty.util.resource.Resource;

 /**
- * <p>
 * This goal will compile jsps for a webapp so that they can be included in a
 * war.
- * </p>
 * <p>
 * At runtime, the plugin will use the jsp2.0 jspc compiler if you are running
 * on a 1.4 or lower jvm. If you are using a 1.5 jvm, then the jsp2.1 compiler
 * will be selected. (this is the same behaviour as the <a
- * href="http://jetty.mortbay.org/maven-plugin">jetty plugin</a> for executing
+ * href="https://www.eclipse.org/jetty/documentation/current/maven-and-jetty.html">jetty plugin</a> for executing
 * webapps).
- * </p>
 * <p>
 * Note that the same java compiler will be used as for on-the-fly compiled
 * jsps, which will be the Eclipse java compiler.
- * </p>
- * 
 * <p>
 * See <a
- * href="http://docs.codehaus.org/display/JETTY/Maven+Jetty+Jspc+Plugin">Usage
+ * href="https://www.eclipse.org/jetty/documentation/current/jetty-jspc-maven-plugin.html">Usage
 * Guide</a> for instructions on using this plugin.
- * </p>
- * 
- * @author janb
 * 
 * @goal jspc
 * @phase process-classes
@ -387,7 +379,7 @@ public class JspcMojo extends AbstractMojo
     * Until Jasper supports the option to generate the srcs in a different dir
     * than the classes, this is the best we can do.
     * 
-     * @throws Exception
+     * @throws Exception if unable to clean srcs
     */
    public void cleanupSrcs() throws Exception
    {
@ -433,7 +425,7 @@ public class JspcMojo extends AbstractMojo
     * If you dont specify the insertionMarker, then the fragment will be
     * inserted at the end of the file just before the &lt;/webapp&gt;
     * 
-     * @throws Exception
+     * @throws Exception if unable to merge the web xml
     */
    public void mergeWebXml() throws Exception
    {