Add JavaDoc for CordovaResourceApi

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

@@ -45,6 +45,27 @@ import java.net.URL;
 import java.nio.channels.FileChannel;
 import java.util.Locale;
 
+/**
+ * What this class provides:
+ * 1. Helpers for reading & writing to URLs.
+ *   - E.g. handles assets, resources, content providers, files, data URIs, http[s]
+ *   - E.g. Can be used to query for mime-type & content length.
+ *
+ * 2. To allow plugins to redirect URLs (via remapUrl).
+ *   - All plugins should call remapUrl() on URLs they receive from JS *before*
+ *     passing the URL onto other utility functions in this class.
+ *   - For an example usage of this, refer to the org.apache.cordova.file plugin.
+ *
+ * 3. It exposes a way to use the OkHttp library that ships with Cordova.
+ *   - Through createHttpConnection().
+ *
+ * Future Work:
+ *   - Consider using a Cursor to query content URLs for their size (like the file plugin does).
+ *   - Allow plugins to remapUri to "cdv-plugin://plugin-name/$ID", which CordovaResourceApi
+ *     would then delegate to pluginManager.getPlugin(plugin-name).openForRead($ID)
+ *     - Currently, plugins *can* do this by remapping to a data: URL, but it's inefficient
+ *       for large payloads.
+ */
 public class CordovaResourceApi {
     @SuppressWarnings("unused")
     private static final String LOG_TAG = "CordovaResourceApi";