[playframework#1115] documentation(code): fix warnings of the javadoc

xael-fry · Mar 9, 2017 · ef4915e · ef4915e
1 parent faf0972
commit ef4915e
Show file tree

Hide file tree

Showing 69 changed files with 3,404 additions and 1,936 deletions.
diff --git a/framework/build.xml b/framework/build.xml
@@ -94,12 +94,13 @@
             <classpath refid="classpath.test"/>
             <doctitle><![CDATA[<h1>Play! ${version}</h1>]]></doctitle>
             <bottom><![CDATA[<a href="http://guillaume.bort.fr">Guillaume Bort</a> &amp; <a href="http://www.zenexity.fr">zenexity</a> - Distributed under <a href="http://www.apache.org/licenses/LICENSE-2.0.html">Apache 2 licence</a>, without any warrantly]]></bottom>
-            <tag name="todo" scope="all" description="To do:"/>
+            <tag name="play.todo" scope="all" description="To do:"/>
+        	  <tag name="todo" scope="all" description="To do:"/>
             <group title="Libs" packages="play.libs.*"/>
             <link offline="false" href="http://docs.oracle.com/javaee/7/api/" />
-            <link offline="false" href="http://docs.oracle.com/javase/7/docs/api/" />      
+            <link offline="false" href="https://docs.oracle.com/javase/8/docs/api//" />      
             <link offline="false" href="http://commons.apache.org/proper/commons-fileupload/apidocs/" />
-            <link offline="false" href="http://google-gson.googlecode.com/svn/tags/gson-2.2.4/docs/javadocs/" />
+            <link offline="false" href="https://static.javadoc.io/com.google.code.gson/gson/2.8.0/" />
             <link offline="false" href="https://docs.jboss.org/hibernate/orm/4.2/javadocs/" />
             <link offline="false" href="http://www.mchange.com/projects/c3p0/apidocs/" />
         </javadoc>

diff --git a/framework/src/play/CorePlugin.java b/framework/src/play/CorePlugin.java
@@ -42,6 +42,10 @@ public class CorePlugin extends PlayPlugin {
 
     /**
      * Get the application status
+     * 
+     * @param json
+     *            true if the status should be return in JSON
+     * @return application status
      */
     public static String computeApplicationStatus(boolean json) {
         if (json) {

diff --git a/framework/src/play/Invoker.java b/framework/src/play/Invoker.java
@@ -13,6 +13,9 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
 
+import com.jamonapi.Monitor;
+import com.jamonapi.MonitorFactory;
+
 import play.Play.Mode;
 import play.classloading.ApplicationClassloader;
 import play.classloading.enhancers.LocalvariablesNamesEnhancer.LocalVariablesNamesTracer;
@@ -23,9 +26,6 @@
 import play.libs.F.Promise;
 import play.utils.PThreadFactory;
 
-import com.jamonapi.Monitor;
-import com.jamonapi.MonitorFactory;
-
 /**
  * Run some code in a Play! context
  */
@@ -38,7 +38,9 @@ public class Invoker {
 
     /**
      * Run the code in a new thread took from a thread pool.
-     * @param invocation The code to run
+     * 
+     * @param invocation
+     *            The code to run
      * @return The future object, to know when the task is completed
      */
     public static Future<?> invoke(Invocation invocation) {
@@ -50,8 +52,11 @@ public static Future<?> invoke(Invocation invocation) {
 
     /**
      * Run the code in a new thread after a delay
-     * @param invocation The code to run
-     * @param millis The time to wait before, in milliseconds
+     * 
+     * @param invocation
+     *            The code to run
+     * @param millis
+     *            The time to wait before, in milliseconds
      * @return The future object, to know when the task is completed
      */
     public static Future<?> invoke(Invocation invocation, long millis) {
@@ -62,7 +67,9 @@ public static Future<?> invoke(Invocation invocation, long millis) {
 
     /**
      * Run the code in the same thread than caller.
-     * @param invocation The code to run
+     * 
+     * @param invocation
+     *            The code to run
      */
     public static void invokeInThread(DirectInvocation invocation) {
         boolean retry = true;
@@ -154,8 +161,10 @@ public <T extends Annotation> boolean isAnnotationPresent(Class<T> clazz) {
         }
 
         /**
-         * Returns the InvocationType for this invocation - Ie: A plugin can use this to
-         * find out if it runs in the context of a background Job
+         * Returns the InvocationType for this invocation - Ie: A plugin can use this to find out if it runs in the
+         * context of a background Job
+         * 
+         * @return the InvocationType for this invocation
          */
         public String getInvocationType() {
             return invocationType;
@@ -186,15 +195,15 @@ public abstract static class Invocation implements Runnable {
 
         /**
          * Override this method
+         * 
          * @throws java.lang.Exception
+         *             Thrown if Invocation encounters any problems
          */
         public abstract void execute() throws Exception;
 
-
         /**
-         * Needs this method to do stuff *before* init() is executed.
-         * The different Invocation-implementations does a lot of stuff in init()
-         * and they might do it before calling super.init()
+         * Needs this method to do stuff *before* init() is executed. The different Invocation-implementations does a
+         * lot of stuff in init() and they might do it before calling super.init()
          */
         protected void preInit() {
             // clear language for this request - we're resolving it later when it is needed
@@ -203,6 +212,8 @@ protected void preInit() {
 
         /**
          * Init the call (especially useful in DEV mode to detect changes)
+         * 
+         * @return true if successful
          */
         public boolean init() {
             Thread.currentThread().setContextClassLoader(Play.classloader);
@@ -217,7 +228,6 @@ public boolean init() {
             return true;
         }
 
-
         public abstract InvocationContext getInvocationContext();
 
         /**
@@ -229,8 +239,7 @@ public void before() {
         }
 
         /**
-         * Things to do after an Invocation.
-         * (if the Invocation code has not thrown any exception)
+         * Things to do after an Invocation. (if the Invocation code has not thrown any exception)
          */
         public void after() {
             Play.pluginCollection.afterInvocation();
@@ -239,13 +248,19 @@ public void after() {
 
         /**
          * Things to do when the whole invocation has succeeded (before + execute + after)
+         * 
+         * @throws java.lang.Exception
+         *             Thrown if Invoker encounters any problems
          */
         public void onSuccess() throws Exception {
             Play.pluginCollection.onInvocationSuccess();
         }
 
         /**
          * Things to do if the Invocation code thrown an exception
+         * 
+         * @param e
+         *            The exception
          */
         public void onException(Throwable e) {
             Play.pluginCollection.onInvocationException(e);
@@ -257,7 +272,9 @@ public void onException(Throwable e) {
 
         /**
          * The request is suspended
+         * 
          * @param suspendRequest
+         *            the suspended request
          */
         public void suspend(Suspend suspendRequest) {
             if (suspendRequest.task != null) {
@@ -276,10 +293,10 @@ public void _finally() {
         }
 
         private void withinFilter(play.libs.F.Function0<Void> fct) throws Throwable {
-          F.Option<PlayPlugin.Filter<Void>> filters = Play.pluginCollection.composeFilters();
-          if (filters.isDefined()) {
-            filters.get().withinFilter(fct);
-          }
+            F.Option<PlayPlugin.Filter<Void>> filters = Play.pluginCollection.composeFilters();
+            if (filters.isDefined()) {
+                filters.get().withinFilter(fct);
+            }
         }
 
         /**
@@ -351,7 +368,8 @@ public InvocationContext getInvocationContext() {
      * Init executor at load time.
      */
     static {
-        int core = Integer.parseInt(Play.configuration.getProperty("play.pool", Play.mode == Mode.DEV ? "1" : ((Runtime.getRuntime().availableProcessors() + 1) + "")));
+        int core = Integer.parseInt(Play.configuration.getProperty("play.pool",
+                Play.mode == Mode.DEV ? "1" : ((Runtime.getRuntime().availableProcessors() + 1) + "")));
         executor = new ScheduledThreadPoolExecutor(core, new PThreadFactory("play"), new ThreadPoolExecutor.AbortPolicy());
     }
 
@@ -364,7 +382,7 @@ public static class Suspend extends PlayException {
          * Suspend for a timeout (in milliseconds).
          */
         long timeout;
-        
+
         /**
          * Wait for task execution.
          */