Bug 776023 - Fix more JavaDoc warnings. r=rnewman

mobile/android/base/sync/Utils.java

@@ -375,7 +375,7 @@ public class Utils {
    * Get names of stages to sync: (ALL intersect SYNC) intersect (ALL minus SKIP).
    *
    * @param knownStageNames collection of known stage names (set ALL above).
-   * @param bundle
+   * @param extras
    *          a <code>Bundle</code> instance (possibly null) optionally containing keys
    *          <code>EXTRAS_KEY_STAGES_TO_SYNC</code> (set SYNC above) and
    *          <code>EXTRAS_KEY_STAGES_TO_SKIP</code> (set SKIP above).

mobile/android/base/sync/config/AccountPickler.java

@@ -20,11 +20,34 @@ import android.content.Context;
 /**
  * Bug 768102: Android deletes Account objects when the Authenticator that owns
  * the Account disappears. This happens when an App is installed to the SD card
- * and the SD card is un-mounted.
+ * and the SD card is un-mounted or the device is rebooted.
  * <p>
- * Bug 769745: We work around this by pickling the current Sync account data
- * every sync and un-pickling when we check if Sync accounts exist (called from
- * Fennec).
+ * Bug 769745: Work around this by pickling the current Sync account data every
+ * sync.
+ * <p>
+ * Bug 735842: Work around this by un-pickling when we check if Sync accounts
+ * exist (called from Fennec).
+ * <p>
+ * Android just doesn't support installing Apps that define long-lived Services
+ * and/or own Account types onto the SD card. The documentation says not to do
+ * it. There are hordes of developers who want to do it, and have tried to
+ * register for almost every "package installation changed" broadcast intent
+ * that Android supports. They all explicitly state that the package that has
+ * changed does *not* receive the broadcast intent, thereby preventing an App
+ * from re-establishing its state.
+ * <p>
+ * <a href="http://developer.android.com/guide/topics/data/install-location.html">Reference.</a>
+ * <p>
+ * <b>Quote</b>: Your AbstractThreadedSyncAdapter and all its sync functionality
+ * will not work until external storage is remounted.
+ * <p>
+ * <b>Quote</b>: Your running Service will be killed and will not be restarted
+ * when external storage is remounted. You can, however, register for the
+ * ACTION_EXTERNAL_APPLICATIONS_AVAILABLE broadcast Intent, which will notify
+ * your application when applications installed on external storage have become
+ * available to the system again. At which time, you can restart your Service.
+ * <p>
+ * Problem: <a href="http://code.google.com/p/android/issues/detail?id=8485">that intent doesn't work</a>!
  */
 public class AccountPickler {
   public static final String LOG_TAG = "AccountPickler";

mobile/android/base/sync/repositories/android/AndroidBrowserBookmarksDataAccessor.java

@@ -172,8 +172,8 @@ public class AndroidBrowserBookmarksDataAccessor extends AndroidBrowserRepositor
    * Bump the modified time of each child.
    * The caller should bump the modified time of the destination if desired.
    *
-   * @param from the source folders.
-   * @param to the destination folder.
+   * @param fromIDs the Android IDs of the source folders.
+   * @param to the Android ID of the destination folder.
    * @return the number of updated rows.
    */
   protected int moveChildren(String[] fromIDs, long to) {

mobile/android/base/sync/repositories/android/BookmarksInsertionManager.java

@@ -290,8 +290,8 @@ public class BookmarksInsertionManager {
      * <p>
      * All exceptions should be caught and all delegate callbacks invoked here.
      *
-     * @param record
-     *          the record to insert.
+     * @param records
+     *          the records to insert.
      */
     public void bulkInsertNonFolders(Collection<BookmarkRecord> records);
   }

mobile/android/base/sync/repositories/android/PasswordsRepositorySession.java

@@ -441,8 +441,9 @@ public class PasswordsRepositorySession extends
 
   /**
    * Insert record and return the record with its updated androidId set.
-   * @param record
-   * @return
+   *
+   * @param record the record to insert.
+   * @return updated record.
    * @throws RemoteException
    */
   public PasswordRecord insert(PasswordRecord record) throws RemoteException {

mobile/android/base/sync/repositories/domain/FormHistoryRecord.java

@@ -14,7 +14,7 @@ import org.mozilla.gecko.sync.repositories.android.RepoUtils;
  *
  * I map a <code>fieldName</code> string to a <code>value</code> string.
  *
- * {@link http://mxr.mozilla.org/services-central/source/services-central/services/sync/modules/engines/forms.js}
+ * @see "<a href='http://mxr.mozilla.org/services-central/source/services-central/services/sync/modules/engines/forms.js'>http://mxr.mozilla.org/services-central/source/services-central/services/sync/modules/engines/forms.js</a>."
  */
 public class FormHistoryRecord extends Record {
   private static final String LOG_TAG = "FormHistoryRecord";

mobile/android/base/sync/setup/activities/ActivityUtils.java

@@ -11,10 +11,9 @@ public class ActivityUtils {
    * Sync key should be a 26-character string, and can include arbitrary
    * capitalization and hyphenation.
    *
-   * @param String
-   *          sync key Sync key entered by user in account setup.
-   * @return String formatted key Sync key in correct format (lower-cased and
-   *         de-hyphenated)
+   * @param key
+   *          Sync key entered by user in account setup.
+   * @return Sync key in correct format (lower-case, no hyphens).
    * @throws InvalidSyncKeyException
    */
   public static String validateSyncKey(String key) throws InvalidSyncKeyException {

mobile/android/base/sync/setup/auth/AccountAuthenticator.java

@@ -85,10 +85,10 @@ public class AccountAuthenticator {
   /**
    * Abort authentication.
    *
+   * @param result
+   *    returned to callback.
    * @param e
    *    Exception causing abort.
-   * @param reason
-   *    Reason for abort.
    */
   public void abort(AuthenticationResult result, Exception e) {
     if (isCanceled) {