style: update & resolve doc block warnings (apache#1774)

* style: resolve throw symbols (except InvalidArgumentException)
* style: resolve unknown symbol & reduce indention for PluginEntry
* fix: define IllegalArgumentException not InvalidArgumentException

Author: erisu

cordova-js-src/plugin/android/app.js

@@ -31,14 +31,14 @@ module.exports = {
     },
 
     /**
-    * Load the url into the webview or into new browser instance.
+    * Load the url into the WebView or into new browser instance.
     *
     * @param url           The URL to load
     * @param props         Properties that can be passed in to the activity:
     *      wait: int                           => wait msec before loading URL
     *      loadingDialog: "Title,Message"      => display a native loading dialog
     *      loadUrlTimeoutValue: int            => time in msec to wait before triggering a timeout error
-    *      clearHistory: boolean              => clear webview history (default=false)
+    *      clearHistory: boolean              => clear WebView history (default=false)
     *      openExternal: boolean              => open in a new browser (default=false)
     *
     * Example:

framework/cordova.gradle

@@ -150,7 +150,7 @@ def doGetConfigPreference(name, defaultValue) {
 }
 
 def doApplyCordovaConfigCustomization() {
-    // Apply user overide properties that comes from the "--gradleArg=-P" parameters
+    // Apply user override properties that comes from the "--gradleArg=-P" parameters
     if (project.hasProperty('cdvMinSdkVersion')) {
         cordovaConfig.MIN_SDK_VERSION = Integer.parseInt('' + cdvMinSdkVersion)
     }

framework/src/org/apache/cordova/AllowListPlugin.java

@@ -39,7 +39,7 @@ public class AllowListPlugin extends CordovaPlugin {
     // Used when instantiated via reflection by PluginManager
     public AllowListPlugin() { }
 
-    // These can be used by embedders to allow Java-configuration of an allow list.
+    // These can be used by plugin developers to allow Java-configuration of an allow list.
     public AllowListPlugin(Context context) {
         this(new AllowList(), new AllowList(), null);
         new CustomConfigXmlParser().parse(context);

framework/src/org/apache/cordova/AuthenticationToken.java

@@ -37,8 +37,7 @@ public String getUserName() {
     /**
      * Sets the user name.
      *
-     * @param userName
-     *            the new user name
+     * @param userName the new user name
      */
     public void setUserName(String userName) {
         this.userName = userName;
@@ -56,8 +55,7 @@ public String getPassword() {
     /**
      * Sets the password.
      *
-     * @param password
-     *            the new password
+     * @param password the new password
      */
     public void setPassword(String password) {
         this.password = password;

framework/src/org/apache/cordova/CallbackMap.java

@@ -54,7 +54,7 @@ public synchronized int registerCallback(CordovaPlugin receiver, int requestCode
      * obtained from registerCallback()
      *
      * @param mappedId      The request code obtained from registerCallback()
-     * @return              The CordovaPlugin and orignal request code that correspond to the
+     * @return              The CordovaPlugin and original request code that correspond to the
      *                      given mappedCode
      */
     public synchronized Pair<CordovaPlugin, Integer> getAndRemoveCallback(int mappedId) {

framework/src/org/apache/cordova/Config.java

@@ -23,7 +23,7 @@ Licensed to the Apache Software Foundation (ASF) under one
 
 import android.app.Activity;
 
-@Deprecated // Use AllowList, CordovaPrefences, etc. directly.
+@Deprecated // Use AllowList, CordovaPreferences, etc. directly.
 public class Config {
     private static final String TAG = "Config";
 

framework/src/org/apache/cordova/CordovaActivity.java

@@ -49,7 +49,7 @@ Licensed to the Apache Software Foundation (ASF) under one
  * application. It should be extended by the user to load the specific
  * html file that contains the application.
  *
- * As an example:
+ * <p>As an example:</p>
  *
  * <pre>
  *     package org.apache.cordova.examples;
@@ -68,17 +68,16 @@ Licensed to the Apache Software Foundation (ASF) under one
  *     }
  * </pre>
  *
- * Cordova xml configuration: Cordova uses a configuration file at
- * res/xml/config.xml to specify its settings. See "The config.xml File"
- * guide in cordova-docs at http://cordova.apache.org/docs for the documentation
- * for the configuration. The use of the set*Property() methods is
- * deprecated in favor of the config.xml file.
+ * <p>Cordova xml configuration: Cordova uses a configuration file at
+ * res/xml/config.xml to specify its settings. See the "Config.xml API" documentation for
+ * configuration details at <a href="https://cordova.apache.org/docs">Apache Cordova Docs</a>.</p>
  *
+ * <p>The use of the set*Property() methods is deprecated in favor of the config.xml file.</p>
  */
 public class CordovaActivity extends AppCompatActivity {
     public static String TAG = "CordovaActivity";
 
-    // The webview for our app
+    // The WebView for our app
     protected CordovaWebView appView;
 
     private static int ACTIVITY_STARTING = 0;
@@ -206,7 +205,7 @@ protected void createViews() {
     /**
      * Construct the default web view object.
      * <p/>
-     * Override this to customize the webview that is used.
+     * Override this to customize the WebView that is used.
      */
     protected CordovaWebView makeWebView() {
         return new CordovaWebViewImpl(makeWebViewEngine());
@@ -227,7 +226,7 @@ public Object onMessage(String id, Object data) {
     }
 
     /**
-     * Load the url into the webview.
+     * Load the url into the WebView.
      */
     public void loadUrl(String url) {
         if (appView == null) {
@@ -250,7 +249,7 @@ protected void onPause() {
 
         if (this.appView != null) {
             // CB-9382 If there is an activity that started for result and main activity is waiting for callback
-            // result, we shoudn't stop WebView Javascript timers, as activity for result might be using them
+            // result, we shouldn't stop WebView Javascript timers, as activity for result might be using them
             boolean keepRunning = this.keepRunning || this.cordovaInterface.activityResultCallback != null;
             this.appView.handlePause(keepRunning);
         }

framework/src/org/apache/cordova/CordovaClientCertRequest.java

@@ -47,8 +47,8 @@ public void cancel()
         request.cancel();
     }
 
-    /*
-     * Returns the host name of the server requesting the certificate.
+    /**
+     * @return the host name of the server requesting the certificate.
      */
     @SuppressLint("NewApi")
     @Override
@@ -57,8 +57,8 @@ public String getHost()
         return request.getHost();
     }
 
-    /*
-     * Returns the acceptable types of asymmetric keys (can be null).
+    /**
+     * @return the acceptable types of asymmetric keys (can be null).
      */
     @SuppressLint("NewApi")
     @Override
@@ -67,8 +67,8 @@ public String[] getKeyTypes()
         return request.getKeyTypes();
     }
 
-    /*
-     * Returns the port number of the server requesting the certificate.
+    /**
+     * @return the port number of the server requesting the certificate.
      */
     @SuppressLint("NewApi")
     @Override
@@ -77,8 +77,8 @@ public int getPort()
         return request.getPort();
     }
 
-    /*
-     * Returns the acceptable certificate issuers for the certificate matching the private key (can be null).
+    /**
+     * @return the acceptable certificate issuers for the certificate matching the private key (can be null).
      */
     @SuppressLint("NewApi")
     @Override
@@ -87,7 +87,7 @@ public Principal[] getPrincipals()
         return request.getPrincipals();
     }
 
-    /*
+    /**
      * Ignore the request for now. Do not remember user's choice.
      */
     @SuppressLint("NewApi")
@@ -97,7 +97,7 @@ public void ignore()
         request.ignore();
     }
 
-    /*
+    /**
      * Proceed with the specified private key and client certificate chain. Remember the user's positive choice and use it for future requests.
      *
      * @param privateKey The privateKey

framework/src/org/apache/cordova/CordovaDialogsHelper.java

@@ -118,8 +118,8 @@ public boolean onKey(DialogInterface dialog, int keyCode, KeyEvent event) {
      * If the client returns true, WebView will assume that the client will
      * handle the prompt dialog and call the appropriate JsPromptResult method.
      *
-     * Since we are hacking prompts for our own purposes, we should not be using them for
-     * this purpose, perhaps we should hack console.log to do this instead!
+     * <p>Since we are hacking prompts for our own purposes, we should not be using them for
+     * this purpose, perhaps we should hack console.log to do this instead!</p>
      */
     public void showPrompt(String message, String defaultValue, final Result result) {
         // Returning false would also show a dialog, but the default one shows the origin (ugly).

framework/src/org/apache/cordova/CordovaInterface.java

@@ -51,7 +51,8 @@ public interface CordovaInterface {
     /**
      * Get the Android activity.
      *
-     * If a custom engine lives outside of the Activity's lifecycle the return value may be null.
+     * <p>If a custom engine lives outside of the Activity's lifecycle the return value
+     * may be null.</p>
      *
      * @return the Activity
      */
@@ -74,7 +75,7 @@ public interface CordovaInterface {
     public Object onMessage(String id, Object data);
 
     /**
-     * Returns a shared thread pool that can be used for background tasks.
+     * @return a shared thread pool that can be used for background tasks.
      */
     public ExecutorService getThreadPool();
 
@@ -89,7 +90,9 @@ public interface CordovaInterface {
     public void requestPermissions(CordovaPlugin plugin, int requestCode, String [] permissions);
 
     /**
-     * Check for a permission.  Returns true if the permission is granted, false otherwise.
+     * Check for a permission.
+     *
+     * @return true if the permission is granted, false otherwise.
      */
     public boolean hasPermission(String permission);
 

framework/src/org/apache/cordova/CordovaInterfaceImpl.java

@@ -135,7 +135,9 @@ public void onCordovaInit(PluginManager pluginManager) {
     }
 
     /**
-     * Routes the result to the awaiting plugin. Returns false if no plugin was waiting.
+     * Routes the result to the awaiting plugin.
+     *
+     * @return false if no plugin was waiting.
      */
     public boolean onActivityResult(int requestCode, int resultCode, Intent intent) {
         CordovaPlugin callback = activityResultCallback;