diff --git a/framework/src/org/apache/cordova/CordovaPlugin.java b/framework/src/org/apache/cordova/CordovaPlugin.java
index 6cd9b0560..ff5cad4cd 100644
--- a/framework/src/org/apache/cordova/CordovaPlugin.java
+++ b/framework/src/org/apache/cordova/CordovaPlugin.java
@@ -416,7 +416,14 @@ public boolean hasPermisssion() {
     }
 
     /**
-     * Called by the system when the user grants permissions
+     * Forwarded system call to the plugin when the user grants permissions,
+     * denies them or the request was interrupted.
+     * This is a legacy method and should not be used anymore.
+     * Instead {@link #onRequestPermissionsResult} should be used.
+     * 
+     * Note: The system calls {@link CordovaActivity#onRequestPermissionsResult(int, String[], int[])},
+     * which calls {@link CordovaInterfaceImpl#onRequestPermissionsResult(int, String[], int[])},
+     * and finally this method.
      *
      * @param requestCode
      * @param permissions
@@ -430,11 +437,17 @@ public void onRequestPermissionResult(int requestCode, String[] permissions,
     }
 
     /**
-     * Called by the system when the user grants permissions
+     * Forwarded system call to the plugin when the user grants permissions,
+     * denies them or the request was interrupted.
+     * 
+     * Note: The system calls {@link CordovaActivity#onRequestPermissionsResult(int, String[], int[])},
+     * which calls {@link CordovaInterfaceImpl#onRequestPermissionsResult(int, String[], int[])},
+     * and finally this method.
      *
      * @param requestCode
      * @param permissions
      * @param grantResults
+     * @see https://developer.android.com/reference/android/app/Activity#onRequestPermissionsResult(int,%20java.lang.String[],%20int[])
      */
     public void onRequestPermissionsResult(int requestCode, String[] permissions,
                                           int[] grantResults) throws JSONException {