From d17da43c82c4edb97514d6138bc208eeba321636 Mon Sep 17 00:00:00 2001
From: Scott Main <smain@google.com>
Date: Thu, 29 Apr 2010 21:42:58 -0700
Subject: docs: revise and add documentation for backup APIs

Change-Id: I0b015a6de16da07ccd31756b8d2329dc2785c2f7
---
 core/java/android/app/backup/BackupAgent.java      | 38 ++++++++--------
 .../java/android/app/backup/BackupAgentHelper.java | 16 +++----
 core/java/android/app/backup/BackupDataInput.java  | 50 +++++++++++-----------
 .../android/app/backup/BackupDataInputStream.java  | 12 +++---
 core/java/android/app/backup/BackupDataOutput.java | 31 +++++++-------
 core/java/android/app/backup/BackupHelper.java     | 41 +++++++++++++-----
 core/java/android/app/backup/BackupManager.java    | 26 +++++------
 core/java/android/app/backup/FileBackupHelper.java |  9 ++--
 .../app/backup/SharedPreferencesBackupHelper.java  | 23 +++++-----
 core/java/android/app/backup/package.html          |  6 ++-
 10 files changed, 141 insertions(+), 111 deletions(-)

(limited to 'core/java/android')

diff --git a/core/java/android/app/backup/BackupAgent.java b/core/java/android/app/backup/BackupAgent.java
index 0bb2cb5..5245da5 100644
--- a/core/java/android/app/backup/BackupAgent.java
+++ b/core/java/android/app/backup/BackupAgent.java
@@ -29,42 +29,44 @@ import android.util.Log;
 import java.io.IOException;
 
 /**
- * {@link android.app.backup.BackupAgent} is the central interface between an
+ * Provides the central interface between an
  * application and Android's data backup infrastructure.  An application that wishes
  * to participate in the backup and restore mechanism will declare a subclass of
  * {@link android.app.backup.BackupAgent}, implement the
- * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}
- * and {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor)} methods,
- * and provide the name of its agent class in the AndroidManifest.xml file via
- * the &lt;application&gt; tag's android:backupAgent attribute.
- * <p>
- * <b>Basic Operation</b>
+ * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) onBackup()}
+ * and {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor) onRestore()} methods,
+ * and provide the name of its backup agent class in its {@code AndroidManifest.xml} file via
+ * the <code><a
+ * href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
+ * tag's {@code android:backupAgent} attribute.
+ * <h3>Basic Operation</h3>
  * <p>
  * When the application makes changes to data that it wishes to keep backed up,
  * it should call the
  * {@link android.app.backup.BackupManager#dataChanged() BackupManager.dataChanged()} method.
- * This notifies the Android backup manager that the application needs an opportunity
- * to update its backup image.  The backup manager, in turn, will then schedule a
+ * This notifies the Android Backup Manager that the application needs an opportunity
+ * to update its backup image.  The Backup Manager, in turn, schedules a
  * backup pass to be performed at an opportune time.
  * <p>
- * Restore operations are typically only performed when applications are first
+ * Restore operations are typically performed only when applications are first
  * installed on a device.  At that time, the operating system checks to see whether
- * there is a previously-saved data set available for the application, and if so,
- * begins an immediate restore pass to deliver that data as part of the installation
+ * there is a previously-saved data set available for the application being installed, and if so,
+ * begins an immediate restore pass to deliver the backup data as part of the installation
  * process.
  * <p>
- * When a backup or restore pass is run, the application's process will be launched
- * (if not already running), the manifest-declared agent class instantiated within
- * that process, and the agent's {@link #onCreate()} method invoked.  This prepares the
+ * When a backup or restore pass is run, the application's process is launched
+ * (if not already running), the manifest-declared backup agent class (in the {@code
+ * android:backupAgent} attribute) is instantiated within
+ * that process, and the agent's {@link #onCreate()} method is invoked.  This prepares the
  * agent instance to run the actual backup or restore logic.  At this point the
  * agent's
  * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) onBackup()} or
  * {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor) onRestore()} method will be
  * invoked as appropriate for the operation being performed.
  * <p>
- * A backup data set consists of one or more "entities," flattened binary data records
- * that are each identified with a key string unique within the data set.  Adding a
- * record to the active data set, or updating an existing record, are done by simply
+ * A backup data set consists of one or more "entities," flattened binary data
+ * records that are each identified with a key string unique within the data set.  Adding a
+ * record to the active data set or updating an existing record is done by simply
  * writing new entity data under the desired key.  Deleting an entity from the data set
  * is done by writing an entity under that key with header specifying a negative data
  * size, and no actual entity data.
diff --git a/core/java/android/app/backup/BackupAgentHelper.java b/core/java/android/app/backup/BackupAgentHelper.java
index 6d73090..d47ca22 100644
--- a/core/java/android/app/backup/BackupAgentHelper.java
+++ b/core/java/android/app/backup/BackupAgentHelper.java
@@ -24,19 +24,19 @@ import java.io.IOException;
  * A convenient {@link BackupAgent} wrapper class that automatically manages
  * heterogeneous data sets within the backup data, each identified by a unique
  * key prefix.  When processing a backup or restore operation, the BackupAgentHelper
- * dispatches to one or more installed {@link BackupHelper helpers} objects, each
+ * dispatches to one or more installed {@link BackupHelper} objects, each
  * of which is responsible for a defined subset of the data being processed.
  * <p>
- * An application will typically extend this class in their own
+ * An application will typically extend this class in its own
  * backup agent. Then, within the agent's {@link BackupAgent#onCreate() onCreate()}
- * method, it will call {@link #addHelper(String, BackupHelper)} one or more times to
+ * method, it will call {@link #addHelper(String, BackupHelper) addHelper()} one or more times to
  * install the handlers for each kind of data it wishes to manage within its backups.
  * <p>
- * The Android framework currently provides two predefined {@link BackupHelper} classes:
- * {@link FileBackupHelper}, which manages the backup and restore of entire files
- * within an application's data directory hierarchy; and {@link SharedPreferencesBackupHelper},
- * which manages the backup and restore of an application's
- * {@link android.content.SharedPreferences} data.
+ * The Android framework currently provides two predefined {@link BackupHelper} classes:</p>
+ * <ul><li>{@link FileBackupHelper} - Manages the backup and restore of entire files
+ * within an application's data directory hierarchy.</li>
+ * <li>{@link SharedPreferencesBackupHelper} - Manages the backup and restore of an
+ * application's {@link android.content.SharedPreferences} data.</li></ul>
  * <p>
  * An application can also implement its own helper classes to work within the
  * {@link BackupAgentHelper} framework.  See the {@link BackupHelper} interface
diff --git a/core/java/android/app/backup/BackupDataInput.java b/core/java/android/app/backup/BackupDataInput.java
index 976e0c9..43b920a 100644
--- a/core/java/android/app/backup/BackupDataInput.java
+++ b/core/java/android/app/backup/BackupDataInput.java
@@ -20,40 +20,42 @@ import java.io.FileDescriptor;
 import java.io.IOException;
 
 /**
- * BackupDataInput is the structured interface used for passing the contents of
- * a backup data set to an application's {@link BackupAgent} class in its
- * {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor)}
+ * Provides the structured interface through which a {@link BackupAgent} reads
+ * information from the backup data set, via its
+ * {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()}
  * method.  The data is presented as a set of "entities," each
  * representing one named record as previously stored by the agent's
- * {@link BackupAgent#onBackup(android.os.ParcelFileDescriptor, BackupDataOutput, android.os.ParcelFileDescriptor)}
- * implementation.  An entity is composed of a descriptive header plus a
- * byte array that holds its raw data.
+ * {@link BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
+ * onBackup()} implementation.  An entity is composed of a descriptive header plus a
+ * byte array that holds the raw data saved in the remote backup.
  * <p>
  * The agent must consume every entity in the data stream, otherwise the
  * restored state of the application will be incomplete.
- * <p>
- * <b>Example</b>
+ * <h3>Example</h3>
  * <p>
  * A typical
- * {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) BackupAgent.onRestore(data, appVersionCode, newState)}
- * implementation might be structured something like this:
+ * {@link BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
+ * onRestore()} implementation might be structured something like this:
  * <pre>
- * while (data.readNextHeader()) {
- *     String key = data.getKey();
- *     int dataSize = data.getDataSize();
+ * public void onRestore(BackupDataInput data, int appVersionCode,
+ *                       ParcelFileDescriptor newState) {
+ *     while (data.readNextHeader()) {
+ *         String key = data.getKey();
+ *         int dataSize = data.getDataSize();
  *
- *     if (key.equals(MY_BACKUP_KEY_ONE)) {
- *         // process this kind of record here
- *         byte[] buffer = new byte[dataSize];
- *         data.readEntityData(buffer, 0, dataSize); // reads the entire entity at once
+ *         if (key.equals(MY_BACKUP_KEY_ONE)) {
+ *             // process this kind of record here
+ *             byte[] buffer = new byte[dataSize];
+ *             data.readEntityData(buffer, 0, dataSize); // reads the entire entity at once
  *
- *         // now 'buffer' holds the raw data and can be processed however
- *         // the agent wishes
- *         processBackupKeyOne(buffer);
- *     } else if (key.equals(MY_BACKUP_KEY_TO_IGNORE) {
- *         // a key we recognize but wish to discard
- *         data.skipEntityData();
- *     } // ... etc.
+ *             // now 'buffer' holds the raw data and can be processed however
+ *             // the agent wishes
+ *             processBackupKeyOne(buffer);
+ *         } else if (key.equals(MY_BACKUP_KEY_TO_IGNORE) {
+ *             // a key we recognize but wish to discard
+ *             data.skipEntityData();
+ *         } // ... etc.
+ *    }
  * }</pre>
  */
 public class BackupDataInput {
diff --git a/core/java/android/app/backup/BackupDataInputStream.java b/core/java/android/app/backup/BackupDataInputStream.java
index 465b3b6..94c7845 100644
--- a/core/java/android/app/backup/BackupDataInputStream.java
+++ b/core/java/android/app/backup/BackupDataInputStream.java
@@ -20,17 +20,17 @@ import java.io.InputStream;
 import java.io.IOException;
 
 /**
- * Used by {@link BackupHelper} classes within the {@link BackupAgentHelper} mechanism,
- * this class provides an {@link java.io.InputStream}-like interface for accessing an
- * entity's data during a restore operation.
+ * Provides an {@link java.io.InputStream}-like interface for accessing an
+ * entity's data during a restore operation. Used by {@link BackupHelper} classes within the {@link
+ * BackupAgentHelper} mechanism.
  * <p>
- * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity(BackupDataInputStream)}
+ * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity()}
  * is called, the current entity's header has already been read from the underlying
  * {@link BackupDataInput}.  The entity's key string and total data size are available
  * through this class's {@link #getKey()} and {@link #size()} methods, respectively.
  * <p class="note">
- * <em>Note:</em> The caller should take care not to seek or close the underlying data
- * source, or to read more than {@link #size()} bytes total from the stream.</p>
+ * <strong>Note:</strong> The caller should take care not to seek or close the underlying data
+ * source, nor read more than {@link #size()} bytes from the stream.</p>
  *
  * @see BackupAgentHelper
  * @see BackupHelper
diff --git a/core/java/android/app/backup/BackupDataOutput.java b/core/java/android/app/backup/BackupDataOutput.java
index a69547a..22668b6 100644
--- a/core/java/android/app/backup/BackupDataOutput.java
+++ b/core/java/android/app/backup/BackupDataOutput.java
@@ -22,27 +22,28 @@ import java.io.FileDescriptor;
 import java.io.IOException;
 
 /**
- * This class is the structured conduit through which a {@link BackupAgent} commits
- * information to the current backup data set.  Data written for backup is presented
+ * Provides the structured interface through which a {@link BackupAgent} commits
+ * information to the backup data set, via its {@link
+ * BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
+ * onBackup()} method.  Data written for backup is presented
  * as a set of "entities," key/value pairs in which each binary data record "value" is
  * named with a string "key."
  * <p>
  * To commit a data record to the backup transport, the agent's
- * {@link BackupAgent#onBackup(android.os.ParcelFileDescriptor, BackupDataOutput, android.os.ParcelFileDescriptor)}
- * method first writes an "entity header" that supplies the key string for the record
+ * {@link BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
+ * onBackup()} method first writes an "entity header" that supplies the key string for the record
  * and the total size of the binary value for the record.  After the header has been
- * written the agent then writes the binary entity value itself.  The entity value can
+ * written, the agent then writes the binary entity value itself.  The entity value can
  * be written in multiple chunks if desired, as long as the total count of bytes written
- * matches what was supplied to {@link #writeEntityHeader(String, int)}.
+ * matches what was supplied to {@link #writeEntityHeader(String, int) writeEntityHeader()}.
  * <p>
  * Entity key strings are considered to be unique within a given application's backup
- * data set.  If a new entity is written under an existing key string, its value will
- * replace any previous value in the transport's remote data store.  A record can be
- * removed entirely from the remote data set by writing a new entity header using the
+ * data set. If a backup agent writes a new entity under an existing key string, its value will
+ * replace any previous value in the transport's remote data store.  You can remove a record
+ * entirely from the remote data set by writing a new entity header using the
  * existing record's key, but supplying a negative <code>dataSize</code> parameter.
- * When doing this the agent does not need to call {@link #writeEntityData(byte[], int)}.
- * <p>
- * <b>Example</b>
+ * When you do so, the agent does not need to call {@link #writeEntityData(byte[], int)}.
+ * <h3>Example</h3>
  * <p>
  * Here is an example illustrating a way to back up the value of a String variable
  * called <code>mStringToBackUp</code>:
@@ -73,9 +74,9 @@ public class BackupDataOutput {
     }
 
     /**
-     * Mark the beginning of one record in the backup data stream.
-     *
-     * @param key
+     * Mark the beginning of one record in the backup data stream. This must be called before
+     * {@link #writeEntityData}.
+     * @param key A string key that uniquely identifies the data record within the application
      * @param dataSize The size in bytes of this record's data.  Passing a dataSize
      *    of -1 indicates that the record under this key should be deleted.
      * @return The number of bytes written to the backup stream
diff --git a/core/java/android/app/backup/BackupHelper.java b/core/java/android/app/backup/BackupHelper.java
index 87b581b..e3f0d54 100644
--- a/core/java/android/app/backup/BackupHelper.java
+++ b/core/java/android/app/backup/BackupHelper.java
@@ -19,7 +19,7 @@ package android.app.backup;
 import android.os.ParcelFileDescriptor;
 
 /**
- * This interface defines the calling interface that {@link BackupAgentHelper} uses
+ * Defines the calling interface that {@link BackupAgentHelper} uses
  * when dispatching backup and restore operations to the installed helpers.
  * Applications can define and install their own helpers as well as using those
  * provided as part of the Android framework.
@@ -43,15 +43,28 @@ public interface BackupHelper {
      * exists now.
      * <p>
      * Implementing this method is much like implementing
-     * {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}
-     * &mdash; the method parameters are the same.  When this method is invoked the
+     * {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)
+     * onBackup()} &mdash; the method parameters are the same.  When this method is invoked the
      * {@code oldState} descriptor points to the beginning of the state data
      * written during this helper's previous backup operation, and the {@code newState}
      * descriptor points to the file location at which the helper should write its
      * new state after performing the backup operation.
      * <p class="note">
-     * <em>Note:</em> The helper should not close or seek either the {@code oldState} or
+     * <strong>Note:</strong> The helper should not close or seek either the {@code oldState} or
      * the {@code newState} file descriptors.</p>
+     *
+     * @param oldState An open, read-only {@link android.os.ParcelFileDescriptor} pointing to the
+     *            last backup state provided by the application. May be
+     *            <code>null</code>, in which case no prior state is being
+     *            provided and the application should perform a full backup.
+     * @param data An open, read/write {@link BackupDataOutput}
+     *            pointing to the backup data destination.
+     *            Typically the application will use backup helper classes to
+     *            write to this file.
+     * @param newState An open, read/write {@link android.os.ParcelFileDescriptor} pointing to an
+     *            empty file. The application should record the final backup
+     *            state here after writing the requested data to the <code>data</code>
+     *            output stream.
      */
     public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
             ParcelFileDescriptor newState);
@@ -61,8 +74,11 @@ public interface BackupHelper {
      * to restore a single entity from the restore data set.  This method will be
      * called for each entity in the data set that belongs to this handler.
      * <p class="note">
-     * <em>Note:</em> Do not close the <code>data</code> stream.  Do not read more than
-     * <code>data.size()</code> bytes from <code>data</code>.</p>
+     * <strong>Note:</strong> Do not close the <code>data</code> stream.  Do not read more than
+     * {@link android.app.backup.BackupDataInputStream#size() size()} bytes from
+     * <code>data</code>.</p>
+     *
+     * @param data An open {@link BackupDataInputStream} from which the backup data can be read.
      */
     public void restoreEntity(BackupDataInputStream data);
 
@@ -71,15 +87,18 @@ public interface BackupHelper {
      * after a restore operation to write the backup state file corresponding to
      * the data as processed by the helper.  The data written here will be
      * available to the helper during the next call to its
-     * {@link #performBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}
-     * method.
+     * {@link #performBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)
+     * performBackup()} method.
      * <p>
-     * Note that this method will be called even if the handler's
-     * {@link #restoreEntity(BackupDataInputStream)} method was never invoked during
+     * This method will be called even if the handler's
+     * {@link #restoreEntity(BackupDataInputStream) restoreEntity()} method was never invoked during
      * the restore operation.
      * <p class="note">
-     * <em>Note:</em> The helper should not close or seek the {@code newState}
+     * <strong>Note:</strong> The helper should not close or seek the {@code newState}
      * file descriptor.</p>
+     *
+     * @param newState A {@link android.os.ParcelFileDescriptor} to which the new state will be
+     * written.
      */
     public void writeNewStateDescription(ParcelFileDescriptor newState);
 }
diff --git a/core/java/android/app/backup/BackupManager.java b/core/java/android/app/backup/BackupManager.java
index 7070827..52dd707 100644
--- a/core/java/android/app/backup/BackupManager.java
+++ b/core/java/android/app/backup/BackupManager.java
@@ -25,9 +25,9 @@ import android.os.ServiceManager;
 import android.util.Log;
 
 /**
- * The BackupManager class is interface through which an application's user interface
- * code will interact with the Android backup service.  Applications simply instantiate one
- * and then issue calls through that instance.
+ * The interface through which an application interacts with the Android backup service to
+ * request backup and restore operations.
+ * Applications instantiate it using the constructor and issue calls through that instance.
  * <p>
  * When an application has made changes to data which should be backed up, a
  * call to {@link #dataChanged()} will notify the backup service. The system
@@ -35,19 +35,16 @@ import android.util.Log;
  * calls to {@link #dataChanged()} have no further effect until the backup
  * operation actually occurs.
  * <p>
- * A backup or restore operation begins with the system launching the
- * {@link android.app.backup.BackupAgent} subclass declared in your manifest. See the
+ * A backup or restore operation for your application begins when the system launches the
+ * {@link android.app.backup.BackupAgent} subclass you've declared in your manifest. See the
  * documentation for {@link android.app.backup.BackupAgent} for a detailed description
  * of how the operation then proceeds.
  * <p>
- * <b>XML attributes</b>
- * <p>
  * Several attributes affecting the operation of the backup and restore mechanism
- * can be set on the &lt;application&gt; tag in the application's
- * AndroidManifest.xml file.  See the documentation on the
- * {@link android.R.styleable#AndroidManifestApplication AndroidManifest.xml's application attributes}
- * for details.
- * 
+ * can be set on the <code><a
+ * href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
+ * tag in your application's AndroidManifest.xml file.
+ *
  * @attr ref android.R.styleable#AndroidManifestApplication_allowBackup
  * @attr ref android.R.styleable#AndroidManifestApplication_backupAgent
  * @attr ref android.R.styleable#AndroidManifestApplication_killAfterRestore
@@ -103,6 +100,8 @@ public class BackupManager {
      * This method requires that the application hold the "android.permission.BACKUP"
      * permission if the package named in the argument does not run under the same uid
      * as the caller.
+     *
+     * @param packageName The package name identifying the application to back up.
      */
     public static void dataChanged(String packageName) {
         checkServiceBinder();
@@ -128,6 +127,9 @@ public class BackupManager {
      * {@link android.app.backup.BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()}
      * method.
      *
+     * @param observer The {@link RestoreObserver} to receive callbacks during the restore
+     * operation. This must not be null.
+     *
      * @return Zero on success; nonzero on error.
      */
     public int requestRestore(RestoreObserver observer) {
diff --git a/core/java/android/app/backup/FileBackupHelper.java b/core/java/android/app/backup/FileBackupHelper.java
index a326941..c6a523a 100644
--- a/core/java/android/app/backup/FileBackupHelper.java
+++ b/core/java/android/app/backup/FileBackupHelper.java
@@ -23,16 +23,17 @@ import android.util.Log;
 import java.io.File;
 
 /**
- * A helper class which can be used in conjunction with
+ * A helper class that can be used in conjunction with
  * {@link android.app.backup.BackupAgentHelper} to manage the backup of a set of
  * files. Whenever backup is performed, all files changed since the last backup
- * will be saved in their entirety.  During the first time the backup happens,
- * every file in the list will be backed up.  Note that this should only be
- * used with small configuration files, not with large binary files.
+ * will be saved in their entirety. When backup first occurs,
+ * every file in the list provided to {@link #FileBackupHelper} will be backed up.
  * <p>
  * During restore, if the helper encounters data for a file that was not
  * specified when the FileBackupHelper object was constructed, that data
  * will be ignored.
+ * <p class="note"><strong>Note:</strong> This should be
+ * used only with small configuration files, not large binary files.
  */
 public class FileBackupHelper extends FileBackupHelperBase implements BackupHelper {
     private static final String TAG = "FileBackupHelper";
diff --git a/core/java/android/app/backup/SharedPreferencesBackupHelper.java b/core/java/android/app/backup/SharedPreferencesBackupHelper.java
index 9efecc5..23b1703 100644
--- a/core/java/android/app/backup/SharedPreferencesBackupHelper.java
+++ b/core/java/android/app/backup/SharedPreferencesBackupHelper.java
@@ -24,18 +24,18 @@ import android.util.Log;
 import java.io.File;
 
 /**
- * A helper class which can be used in conjunction with
+ * A helper class that can be used in conjunction with
  * {@link android.app.backup.BackupAgentHelper} to manage the backup of
- * {@link android.content.SharedPreferences}. Whenever a backup is performed it
- * will back up all named shared preferences which have changed since the last
+ * {@link android.content.SharedPreferences}. Whenever a backup is performed, it
+ * will back up all named shared preferences that have changed since the last
  * backup operation.
  * <p>
- * To use this class, the application's agent class should extend
+ * To use this class, the application's backup agent class should extend
  * {@link android.app.backup.BackupAgentHelper}.  Then, in the agent's
  * {@link BackupAgent#onCreate()} method, an instance of this class should be
  * allocated and installed as a backup/restore handler within the BackupAgentHelper
- * framework.  An implementation of an agent supporting backup and restore for
- * an application that wishes to back up two groups of {@link android.content.SharedPreferences}
+ * framework.  For example, an agent supporting backup and restore for
+ * an application with two groups of {@link android.content.SharedPreferences}
  * data might look something like this:
  * <pre>
  * import android.app.backup.BackupAgentHelper;
@@ -59,12 +59,12 @@ import java.io.File;
  *     }
  * }</pre>
  * <p>
- * No further implementation is needed; the BackupAgentHelper mechanism automatically
+ * No further implementation is needed; the {@link BackupAgentHelper} mechanism automatically
  * dispatches the
  * {@link BackupAgent#onBackup(android.os.ParcelFileDescriptor, BackupDataOutput, android.os.ParcelFileDescriptor) BackupAgent.onBackup()}
  * and
  * {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) BackupAgent.onRestore()}
- * callbacks to the SharedPreferencesBackupHelper as appropriate.  
+ * callbacks to the SharedPreferencesBackupHelper as appropriate.
  */
 public class SharedPreferencesBackupHelper extends FileBackupHelperBase implements BackupHelper {
     private static final String TAG = "SharedPreferencesBackupHelper";
@@ -77,8 +77,9 @@ public class SharedPreferencesBackupHelper extends FileBackupHelperBase implemen
      * Construct a helper for backing up and restoring the
      * {@link android.content.SharedPreferences} under the given names.
      *
-     * @param context
-     * @param prefGroups
+     * @param context The application {@link android.content.Context}
+     * @param prefGroups The names of each {@link android.content.SharedPreferences} file to
+     * back up
      */
     public SharedPreferencesBackupHelper(Context context, String... prefGroups) {
         super(context);
@@ -88,7 +89,7 @@ public class SharedPreferencesBackupHelper extends FileBackupHelperBase implemen
     }
 
     /**
-     * Backs up the configured SharedPreferences groups
+     * Backs up the configured {@link android.content.SharedPreferences} groups.
      */
     public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
             ParcelFileDescriptor newState) {
diff --git a/core/java/android/app/backup/package.html b/core/java/android/app/backup/package.html
index 2a5b628..e2518ec 100644
--- a/core/java/android/app/backup/package.html
+++ b/core/java/android/app/backup/package.html
@@ -1,7 +1,9 @@
 <HTML>
 <BODY>
-<p>Package containing the backup and restore functionality available to
-applications. All backup management is controlled through
+<p>Contains the backup and restore functionality available to
+applications. If a user wipes the data on their device or upgrades to a new Android-powered
+device, all applications that have enabled backup will restore the user's previous data and/or
+preferences. {@more} All backup management is controlled through
 {@link android.app.backup.BackupManager}.  Individual backup functionality is
 implemented through a subclass {@link android.app.backup.BackupAgent} and a
 simple and easy-to-use implementation is provided in
-- 
cgit v1.1