Add JavaDoc for SyncResult

http://b/2420252

Change-Id: I88be5232d54959f6ec3480c36751a8fb7dc369fd

1 files changed, 117 insertions, 2 deletions

diff --git a/core/java/android/content/SyncResult.java b/core/java/android/content/SyncResult.java
index 18abebe..8b0afbd 100644
--- a/core/java/android/content/SyncResult.java
+++ b/core/java/android/content/SyncResult.java
@@ -20,30 +20,110 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * This class is used to store information about the result of a sync
+ * This class is used to communicate the results of a sync operation to the SyncManager.
+ * Based on the values here the SyncManager will determine the disposition of the
+ * sync and whether or not a new sync operation needs to be scheduled in the future.
+ *
  */
 public final class SyncResult implements Parcelable {
+    /**
+     * Used to indicate that the SyncAdapter is already performing a sync operation, though
+     * not necessarily for the requested account and authority and that it wasn't able to
+     * process this request. The SyncManager will reschedule the request to run later.
+     */
     public final boolean syncAlreadyInProgress;
+
+    /**
+     * Used to indicate that the SyncAdapter determined that it would need to issue
+     * too many delete operations to the server in order to satisfy the request
+     * (as defined by the SyncAdapter). The SyncManager will record
+     * that the sync request failed and will cause a System Notification to be created
+     * asking the user what they want to do about this. It will give the user a chance to
+     * choose between (1) go ahead even with those deletes, (2) revert the deletes,
+     * or (3) take no action. If the user decides (1) or (2) the SyncManager will issue another
+     * sync request with either {@link ContentResolver#SYNC_EXTRAS_OVERRIDE_TOO_MANY_DELETIONS}
+     * or {@link ContentResolver#SYNC_EXTRAS_DISCARD_LOCAL_DELETIONS} set in the extras.
+     * It is then up to the SyncAdapter to decide how to honor that request.
+     */
     public boolean tooManyDeletions;
+
+    /**
+     * Used to indicate that the SyncAdapter experienced a hard error due to trying the same
+     * operation too many times (as defined by the SyncAdapter). The SyncManager will record
+     * that the sync request failed and it will not reschedule the request.
+     */
     public boolean tooManyRetries;
+
+    /**
+     * Used to indicate that the SyncAdapter experienced a hard error due to an error it
+     * received from interacting with the storage later. The SyncManager will record that
+     * the sync request failed and it will not reschedule the request.
+     */
     public boolean databaseError;
+
+    /**
+     * If set the SyncManager will request an immediate sync with the same Account and authority
+     * (but empty extras Bundle) as was used in the sync request.
+     */
     public boolean fullSyncRequested;
+
+    /**
+     * This field is ignored by the SyncManager.
+     */
     public boolean partialSyncUnavailable;
+
+    /**
+     * This field is ignored by the SyncManager.
+     */
     public boolean moreRecordsToGet;
 
-    // in seconds since epoch
+    /**
+     * Used to indicate to the SyncManager that future sync requests that match the request's
+     * Account and authority should be delayed at least this many seconds.
+     */
     public long delayUntil;
+
+    /**
+     * Used to hold extras statistics about the sync operation. Some of these indicate that
+     * the sync request resulted in a hard or soft error, others are for purely informational
+     * purposes.
+     */
     public final SyncStats stats;
+
+    /**
+     * This instance of a SyncResult is returned by the SyncAdapter in response to a
+     * sync request when a sync is already underway. The SyncManager will reschedule the
+     * sync request to try again later.
+     */
     public static final SyncResult ALREADY_IN_PROGRESS;
 
     static {
         ALREADY_IN_PROGRESS = new SyncResult(true);
     }
 
+    /**
+     * Create a "clean" SyncResult. If this is returned without any changes then the
+     * SyncManager will consider the sync to have completed successfully. The various fields
+     * can be set by the SyncAdapter in order to give the SyncManager more information as to
+     * the disposition of the sync.
+     * <p>
+     * The errors are classified into two broad categories: hard errors and soft errors.
+     * Soft errors are retried with exponential backoff. Hard errors are not retried (except
+     * when the hard error is for a {@link ContentResolver#SYNC_EXTRAS_UPLOAD} request,
+     * in which the request is retryed without the {@link ContentResolver#SYNC_EXTRAS_UPLOAD}
+     * extra set). The SyncManager checks the type of error by calling
+     * {@link SyncResult#hasHardError()} and  {@link SyncResult#hasSoftError()}. If both are
+     * true then the SyncManager treats it as a hard error, not a soft error.
+     */
     public SyncResult() {
         this(false);
     }
 
+    /**
+     * Internal helper for creating a clean SyncResult or one that indicated that
+     * a sync is already in progress.
+     * @param syncAlreadyInProgress if true then set the {@link #syncAlreadyInProgress} flag
+     */
     private SyncResult(boolean syncAlreadyInProgress) {
         this.syncAlreadyInProgress = syncAlreadyInProgress;
         this.tooManyDeletions = false;
@@ -67,6 +147,21 @@ public final class SyncResult implements Parcelable {
         stats = new SyncStats(parcel);
     }
 
+    /**
+     * Convenience method for determining if the SyncResult indicates that a hard error
+     * occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does
+     * when it sees a hard error.
+     * <p>
+     * A hard error is indicated when any of the following is true:
+     * <ul>
+     * <li> {@link SyncStats#numParseExceptions} > 0
+     * <li> {@link SyncStats#numConflictDetectedExceptions} > 0
+     * <li> {@link SyncStats#numAuthExceptions} > 0
+     * <li> {@link #tooManyDeletions}
+     * <li> {@link #tooManyRetries}
+     * <li> {@link #databaseError}
+     * @return true if a hard error is indicated
+     */
     public boolean hasHardError() {
         return stats.numParseExceptions > 0
                 || stats.numConflictDetectedExceptions > 0
@@ -76,10 +171,26 @@ public final class SyncResult implements Parcelable {
                 || databaseError;
     }
 
+    /**
+     * Convenience method for determining if the SyncResult indicates that a soft error
+     * occurred. See {@link #SyncResult()} for an explanation of what the SyncManager does
+     * when it sees a soft error.
+     * <p>
+     * A soft error is indicated when any of the following is true:
+     * <ul>
+     * <li> {@link SyncStats#numIoExceptions} > 0
+     * <li> {@link #syncAlreadyInProgress}
+     * </ul>
+     * @return true if a hard error is indicated
+     */
     public boolean hasSoftError() {
         return syncAlreadyInProgress || stats.numIoExceptions > 0;
     }
 
+    /**
+     * A convenience method for determining of the SyncResult indicates that an error occurred.
+     * @return true if either a soft or hard error occurred
+     */
     public boolean hasError() {
         return hasSoftError() || hasHardError();
     }
@@ -90,6 +201,10 @@ public final class SyncResult implements Parcelable {
                 || stats.numUpdates > 0;
     }
 
+    /**
+     * Clears the SyncResult to a clean state. Throws an {@link UnsupportedOperationException}
+     * if this is called when {@link #syncAlreadyInProgress} is set.
+     */
     public void clear() {
         if (syncAlreadyInProgress) {
             throw new UnsupportedOperationException(