style: cleanup some of the comment blocks

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

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

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

@@ -47,8 +47,8 @@ public class CordovaClientCertRequest implements ICordovaClientCertRequest {
         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 class CordovaClientCertRequest implements ICordovaClientCertRequest {
         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 class CordovaClientCertRequest implements ICordovaClientCertRequest {
         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 class CordovaClientCertRequest implements ICordovaClientCertRequest {
         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 class CordovaClientCertRequest implements ICordovaClientCertRequest {
         return request.getPrincipals();
     }
 
-    /*
+    /**
      * Ignore the request for now. Do not remember user's choice.
      */
     @SuppressLint("NewApi")
@@ -97,7 +97,7 @@ public class CordovaClientCertRequest implements ICordovaClientCertRequest {
         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/CordovaInterface.java

@@ -74,7 +74,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 +89,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 class CordovaInterfaceImpl implements CordovaInterface {
     }
 
     /**
-     * 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;

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

@@ -79,7 +79,7 @@ public class CordovaPlugin {
     }
 
     /**
-     * Returns the plugin's service name (what you'd use when calling pluginManger.getPlugin())
+     * @return the plugin's service name (what you'd use when calling pluginManger.getPlugin())
      */
     public String getServiceName() {
         return serviceName;
@@ -289,7 +289,7 @@ public class CordovaPlugin {
      * Allows plugins to handle a link being clicked. Return true here to cancel the navigation.
      *
      * @param url           The URL that is trying to be loaded in the Cordova webview.
-     * @return              Return true to prevent the URL from loading. Default is false.
+     * @return              true to prevent the URL from loading. Default is false.
      */
     public boolean onOverrideUrlLoading(String url) {
         return false;
@@ -362,7 +362,6 @@ public class CordovaPlugin {
      * @param handler           The HttpAuthHandler used to set the WebView's response
      * @param host              The host requiring authentication
      * @param realm             The realm for which authentication is required
-     *
      * @return                  Returns True if plugin will resolve this auth challenge, otherwise False
      *
      */
@@ -376,8 +375,7 @@ public class CordovaPlugin {
      *
      * @param view              The WebView that is initiating the callback
      * @param request           The client certificate request
-     *
+     * @return                  True if plugin will resolve this auth challenge, otherwise False
-     * @return                  Returns True if plugin will resolve this auth challenge, otherwise False
      *
      */
     public boolean onReceivedClientCertRequest(CordovaWebView view, ICordovaClientCertRequest request) {
@@ -396,20 +394,17 @@ public class CordovaPlugin {
      * Called by the Plugin Manager when we need to actually request permissions
      *
      * @param requestCode   Passed to the activity to track the request
-     *
+     * @return              The permission that was stored in the plugin
-     * @return              Returns the permission that was stored in the plugin
      */
-
     public void requestPermissions(int requestCode) {
     }
 
-    /*
+    /**
      * Called by the WebView implementation to check for geolocation permissions, can be used
      * by other Java methods in the event that a plugin is using this as a dependency.
      *
-     * @return          Returns true if the plugin has all the permissions it needs to operate.
+     * @return          True if the plugin has all the permissions it needs to operate.
      */
-
     public boolean hasPermisssion() {
         return true;
     }
@@ -420,7 +415,6 @@ public class CordovaPlugin {
      * @param requestCode
      * @param permissions
      * @param grantResults
-     *
      * @deprecated Use {@link #onRequestPermissionsResult} instead.
      */
     @Deprecated
@@ -443,6 +437,7 @@ public class CordovaPlugin {
 
     /**
      * Allow plugins to supply a PathHandler for the WebViewAssetHandler
+     *
      * @return a CordovaPluginPathHandler which listen for paths and returns a response
      */
     public CordovaPluginPathHandler getPathHandler() {

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

@@ -143,8 +143,7 @@ public class CordovaResourceApi {
     }
 
     /**
-     * Returns a File that points to the resource, or null if the resource
+     * @return A file that points to the resource, or null if the resource is not on the local filesystem.
-     * is not on the local filesystem.
      */
     public File mapUriToFile(Uri uri) {
         assertBackgroundThread();
@@ -223,6 +222,7 @@ public class CordovaResourceApi {
 
     /**
      * Opens a stream to the given URI, also providing the MIME type & length.
+     *
      * @return Never returns null.
      * @throws Throws an InvalidArgumentException for relative URIs. Relative URIs should be
      *     resolved before being passed into this function.
@@ -235,6 +235,7 @@ public class CordovaResourceApi {
 
     /**
      * Opens a stream to the given URI, also providing the MIME type & length.
+     *
      * @return Never returns null.
      * @throws Throws an InvalidArgumentException for relative URIs. Relative URIs should be
      *     resolved before being passed into this function.
@@ -320,6 +321,7 @@ public class CordovaResourceApi {
 
     /**
      * Opens a stream to the given URI.
+     *
      * @return Never returns null.
      * @throws Throws an InvalidArgumentException for relative URIs. Relative URIs should be
      *     resolved before being passed into this function.

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

@@ -71,6 +71,7 @@ public class CoreAndroid extends CordovaPlugin {
      * @param action            The action to execute.
      * @param args              JSONArry of arguments for the plugin.
      * @param callbackContext   The callback context from which we were invoked.
+     *
      * @return                  A PluginResult object with a status and message.
      */
     @Override
@@ -334,9 +335,8 @@ public class CoreAndroid extends CordovaPlugin {
         }
     }
 
-    /*
+    /**
      * Unregister the receiver
-     *
      */
     @Override
     public void onDestroy()

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

@@ -31,32 +31,32 @@ public interface ICordovaClientCertRequest {
      */
     public void cancel();
 
-    /*
+    /**
-     * Returns the host name of the server requesting the certificate.
+     * @return the host name of the server requesting the certificate.
      */
     public String getHost();
 
-    /*
+    /**
-     * Returns the acceptable types of asymmetric keys (can be null).
+     * @return the acceptable types of asymmetric keys (can be null).
      */
     public String[] getKeyTypes();
 
-    /*
+    /**
-     * Returns the port number of the server requesting the certificate.
+     * @return the port number of the server requesting the certificate.
      */
     public int 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).
      */
     public Principal[] getPrincipals();
 
-    /*
+    /**
      * Ignore the request for now. Do not remember user's choice.
      */
     public void 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/NativeToJsMessageQueue.java

@@ -124,12 +124,10 @@ public class NativeToJsMessageQueue {
     }
 
     /**
-     * Combines and returns queued messages combined into a single string.
-     *
      * Combines as many messages as possible, without exceeding
      * COMBINED_RESPONSE_CUTOFF in case of multiple response messages.
      *
-     * Returns null if the queue is empty.
+     * @return a string of queued messages combined or null if the queue is empty.
      */
     public String popAndEncode(boolean fromOnlineEvent) {
         synchronized (this) {

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

@@ -66,7 +66,6 @@ public class PermissionHelper {
      *
      * @param plugin        The plugin the permission is being checked against
      * @param permission    The permission to be checked
-     *
      * @return              True if the permission has already been granted and false otherwise
      */
     public static boolean hasPermission(CordovaPlugin plugin, String permission) {

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

@@ -252,9 +252,7 @@ public class PluginManager {
      * @param handler           The HttpAuthHandler used to set the WebView's response
      * @param host              The host requiring authentication
      * @param realm             The realm for which authentication is required
-     *
+     * @return                  True if there is a plugin which will resolve this auth challenge, otherwise False
-     * @return                  Returns True if there is a plugin which will resolve this auth challenge, otherwise False
-     *
      */
     public boolean onReceivedHttpAuthRequest(CordovaWebView view, ICordovaHttpAuthHandler handler, String host, String realm) {
         synchronized (this.pluginMap) {
@@ -273,9 +271,7 @@ public class PluginManager {
      *
      * @param view              The WebView that is initiating the callback
      * @param request           The client certificate request
-     *
+     * @return                  True if plugin will resolve this auth challenge, otherwise False
-     * @return                  Returns True if plugin will resolve this auth challenge, otherwise False
-     *
      */
     public boolean onReceivedClientCertRequest(CordovaWebView view, ICordovaClientCertRequest request) {
         synchronized (this.pluginMap) {
@@ -400,7 +396,7 @@ public class PluginManager {
      * the default policy is applied.
      *
      * @param url       The URL that is being requested.
-     * @return          Returns true to allow the resource to load,
+     * @return          true to allow the resource to load,
      *                  false to block the resource.
      */
     public boolean shouldAllowRequest(String url) {
@@ -440,7 +436,7 @@ public class PluginManager {
      * the default policy is applied.
      *
      * @param url       The URL that is being requested.
-     * @return          Returns true to allow the navigation,
+     * @return          true to allow the navigation,
      *                  false to block the navigation.
      */
     public boolean shouldAllowNavigation(String url) {
@@ -490,7 +486,7 @@ public class PluginManager {
      * the default policy is applied.
      *
      * @param url       The URL that is being requested.
-     * @return          Returns true to allow the URL to launch an intent,
+     * @return          true to allow the URL to launch an intent,
      *                  false to block the intent.
      */
     public Boolean shouldOpenExternalUrl(String url) {

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

@@ -118,8 +118,7 @@ public class PluginResult {
     }
 
     /**
-     * If messageType == MESSAGE_TYPE_STRING, then returns the message string.
+     * @return message string when messageType is MESSAGE_TYPE_STRING otherwise null.
-     * Otherwise, returns null.
      */
     public String getStrMessage() {
         return strMessage;

framework/src/org/apache/cordova/engine/SystemWebChromeClient.java

@@ -184,6 +184,7 @@ public class SystemWebChromeClient extends WebChromeClient {
     /**
      * Ask the host application for a custom progress view to show while
      * a <video> is loading.
+     *
      * @return View The progress view.
      */
     public View getVideoLoadingProgressView() {

framework/src/org/apache/cordova/engine/SystemWebViewClient.java

@@ -332,7 +332,6 @@ public class SystemWebViewClient extends WebViewClient {
      *
      * @param host
      * @param realm
-     *
      * @return the authentication token or null if did not exist
      */
     public AuthenticationToken removeAuthenticationToken(String host, String realm) {
@@ -350,7 +349,6 @@ public class SystemWebViewClient extends WebViewClient {
      *
      * @param host
      * @param realm
-     *
      * @return the authentication token
      */
     public AuthenticationToken getAuthenticationToken(String host, String realm) {