Merge pull request #1119 from xael-fry/1115_fixJavadoc

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

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>

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) {

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.
  */