CB-5490: add javadoc target to ant script

- add javadoc target to ant script. It must be invoked explicitly to run.
- ignore the generated javadoc html directories.
- clean up javadoc errors in source files.
- upon invoking 'clean' target, erase generated jar and javadoc

.gitignore

@@ -14,6 +14,8 @@ framework/assets/www/.DS_Store
 framework/assets/www/cordova-*.js
 framework/assets/www/phonegap-*.js
 framework/libs
+framework/javadoc-public
+framework/javadoc-private
 test/libs
 example
 ./test

framework/build.xml

@@ -95,6 +95,13 @@
     <target name="-post-compile">
     </target>
 -->
+    <target name="-pre-clean">
+        <!-- delete generated javadoc -->
+        <delete dir="javadoc-public" failonerror="false" />
+        <delete dir="javadoc-private" failonerror="false" />
+        <!-- delete generated jar -->
+        <delete file="cordova-${version}.jar" failonerror="false" />
+    </target>
 
     <!-- Import the actual build file.
 
@@ -120,7 +127,31 @@
          that includes all JavaScript code.
     -->
     <target name="jar" depends="-compile">
-      <jar jarfile="cordova-${version}.jar" basedir="bin/classes" excludes="org/apache/cordova/R.class,org/apache/cordova/R$*.class"/>
+        <jar
+            basedir="bin/classes"
+            excludes="org/apache/cordova/R.class,org/apache/cordova/R$*.class"
+            jarfile="cordova-${version}.jar" />
+    </target>
+    
+    <target name="javadoc">
+        <delete dir="javadoc-public" failonerror="false" />
+        <javadoc
+            access="public" 
+            destdir="javadoc-public"
+            classpath="${sdk.dir}/platforms/${target}/android.jar">
+            <packageset dir="src">
+                <include name="org/apache/cordova/**" />
+            </packageset>
+        </javadoc>
+        <delete dir="javadoc-private" failonerror="false" />
+        <javadoc
+            access="private" 
+            destdir="javadoc-private"
+            classpath="${sdk.dir}/platforms/${target}/android.jar">
+            <packageset dir="src">
+                <include name="org/apache/cordova/**" />
+            </packageset>
+        </javadoc>
     </target>
 
     <!-- tests for Java files -->

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

@@ -208,7 +208,7 @@ public class Config {
      * Determine if URL is in approved list of URLs to load.
      *
      * @param url
-     * @return
+     * @return true if whitelisted
      */
     public static boolean isUrlWhiteListed(String url) {
         if (self == null) {

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

@@ -63,13 +63,14 @@ import android.widget.LinearLayout;
  * html file that contains the application.
  *
  * As an example:
- *
+ * 
+ * <pre>
  *     package org.apache.cordova.examples;
  *     import android.os.Bundle;
  *     import org.apache.cordova.*;
  *
  *     public class Example extends CordovaActivity {
- *       @Override
+ *       &#64;Override
  *       public void onCreate(Bundle savedInstanceState) {
  *         super.onCreate(savedInstanceState);
  *
@@ -85,9 +86,11 @@ import android.widget.LinearLayout;
  *         super.loadUrl("file:///android_asset/www/index.html", 3000); // show splash screen 3 sec before loading app
  *       }
  *     }
- *
+ * </pre>
+ * 
  * Properties: The application can be configured using the following properties:
- *
+ * 
+ * <pre>
  *      // Display a native loading dialog when loading app.  Format for value = "Title,Message".
  *      // (String - default=null)
  *      super.setStringProperty("loadingDialog", "Wait,Loading Demo...");
@@ -114,15 +117,19 @@ import android.widget.LinearLayout;
  *
  *      // Enable app to keep running in background. (Boolean - default=true)
  *      super.setBooleanProperty("keepRunning", false);
+ * </pre>
  *
  * Cordova.xml configuration:
+ * 
+ * <pre>
  *      Cordova uses a configuration file at res/xml/cordova.xml to specify the following settings.
  *
  *      Approved list of URLs that can be loaded into Cordova
- *          <access origin="http://server regexp" subdomains="true" />
+ *          &lt;access origin="http://server regexp" subdomains="true" /&gt;
  *      Log level: ERROR, WARN, INFO, DEBUG, VERBOSE (default=ERROR)
- *          <log level="DEBUG" />
+ *          &lt;log level="DEBUG" /&gt;
- *
+ * </pre>
+ * 
  */
 public class CordovaActivity extends Activity implements CordovaInterface {
     public static String TAG = "CordovaActivity";
@@ -291,7 +298,7 @@ public class CordovaActivity extends Activity implements CordovaInterface {
     /**
      * Get the Android activity.
      *
-     * @return
+     * @return the Activity
      */
     public Activity getActivity() {
         return this;
@@ -544,7 +551,7 @@ public class CordovaActivity extends Activity implements CordovaInterface {
      *
      * @param name
      * @param defaultValue
-     * @return
+     * @return the boolean value of the named property
      */
     public boolean getBooleanProperty(String name, boolean defaultValue) {
         Bundle bundle = this.getIntent().getExtras();
@@ -575,7 +582,7 @@ public class CordovaActivity extends Activity implements CordovaInterface {
      *
      * @param name
      * @param defaultValue
-     * @return
+     * @return the int value for the named property
      */
     public int getIntegerProperty(String name, int defaultValue) {
         Bundle bundle = this.getIntent().getExtras();
@@ -600,7 +607,7 @@ public class CordovaActivity extends Activity implements CordovaInterface {
      *
      * @param name
      * @param defaultValue
-     * @return
+     * @return the String value for the named property
      */
     public String getStringProperty(String name, String defaultValue) {
         Bundle bundle = this.getIntent().getExtras();
@@ -620,7 +627,7 @@ public class CordovaActivity extends Activity implements CordovaInterface {
      *
      * @param name
      * @param defaultValue
-     * @return
+     * @return the double value for the named property
      */
     public double getDoubleProperty(String name, double defaultValue) {
         Bundle bundle = this.getIntent().getExtras();
@@ -815,6 +822,7 @@ public class CordovaActivity extends Activity implements CordovaInterface {
      * @param serviceType
      * @param className
      */
+    @Deprecated
     public void addService(String serviceType, String className) {
         if (this.appView != null && this.appView.pluginManager != null) {
             this.appView.pluginManager.addService(serviceType, className);
@@ -1013,7 +1021,7 @@ public class CordovaActivity extends Activity implements CordovaInterface {
      * Determine if URL is in approved list of URLs to load.
      *
      * @param url
-     * @return
+     * @return true if the url is whitelisted
      */
     public boolean isUrlWhiteListed(String url) {
         return Config.isUrlWhiteListed(url);
@@ -1044,8 +1052,10 @@ public class CordovaActivity extends Activity implements CordovaInterface {
     /**
      * Get Activity context.
      *
-     * @return
+     * @return self
+     * @deprecated
      */
+    @Deprecated
     public Context getContext() {
         LOG.d(TAG, "This will be deprecated December 2012");
         return this;

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

@@ -51,7 +51,7 @@ public interface CordovaInterface {
     /**
      * Get the Android activity.
      *
-     * @return
+     * @return the Activity
      */
     public abstract Activity getActivity();
     

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

@@ -321,10 +321,10 @@ public class CordovaWebView extends WebView {
     }
 
 	/**
-	 * Override this method to decide wether or not you need to request the
+	 * Override this method to decide whether or not you need to request the
 	 * focus when your application start
 	 * 
-	 * @return
+	 * @return true unless this method is overriden to return a different value
 	 */
     protected boolean shouldRequestFocusOnInit() {
 		return true;
@@ -642,7 +642,7 @@ public class CordovaWebView extends WebView {
      *
      * @param name
      * @param defaultValue
-     * @return
+     * @return the String value for the named property
      */
     public String getProperty(String name, String defaultValue) {
         Bundle bundle = this.cordova.getActivity().getIntent().getExtras();
@@ -949,7 +949,7 @@ public class CordovaWebView extends WebView {
      * if the video overlay is showing then we need to know 
      * as it effects back button handling
      * 
-     * @return
+     * @return true if custom view is showing
      */
     public boolean isCustomViewShowing() {
         return mCustomView != null;

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

@@ -65,7 +65,7 @@ public class LOG {
      * Determine if log level will be logged
      *
      * @param logLevel
-     * @return
+     * @return true if the parameter passed in is greater than or equal to the current log level
      */
     public static boolean isLoggable(int logLevel) {
         return (logLevel >= LOGLEVEL);

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

@@ -107,7 +107,7 @@ public class PluginEntry {
      * Get the class.
      *
      * @param clazz
-     * @return
+     * @return a reference to the named class
      * @throws ClassNotFoundException
      */
     @SuppressWarnings("rawtypes")

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

@@ -339,7 +339,7 @@ public class PluginManager {
      *
      * @param id                The message id
      * @param data              The message data
-     * @return
+     * @return                  Object to stop propagation or null
      */
     public Object postMessage(String id, Object data) {
         Object obj = this.ctx.onMessage(id, data);

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

@@ -149,7 +149,7 @@ public class Whitelist {
      * Determine if URL is in approved list of URLs to load.
      *
      * @param uri
-     * @return
+     * @return true if wide open or whitelisted
      */
     public boolean isUrlWhiteListed(String uri) {
         // If there is no whitelist, then it's wide open