Add additional docs for offline storage

This adds additional text explaining how to use the Storage API.

Change-Id: Icff55d6fe19e91f983ffb3e4a786f2beefe9ae8f

Author: joeyparrish

lib/offline/storage.js

@@ -40,6 +40,11 @@ goog.require('shaka.util.StreamUtils');
  * stored manifests.  Playback of offline manifests are done using Player
  * using the special URI (e.g. 'offline:12').
  *
+ * First, check support() to see if offline is supported by the platform.
+ * Second, configure() the storage object with callbacks to your application.
+ * Third, call store(), remove(), or list() as needed.
+ * When done, call destroy().
+ *
  * @param {shaka.Player} player
  *   The player instance to pull configuration data from.
  *
@@ -94,7 +99,9 @@ shaka.offline.Storage = function(player) {
 
 
 /**
- * Gets whether offline storage is supported.
+ * Gets whether offline storage is supported.  Returns true if offline storage
+ * is supported for clear content.  Support for offline storage of encrypted
+ * content will not be determined until storage is attempted.
  *
  * @return {boolean}
  * @export
@@ -148,6 +155,12 @@ shaka.offline.Storage.prototype.destroy = function() {
  * Sets configuration values for Storage.  This is not associated with
  * Player.configure and will not change Player.
  *
+ * There are two important callbacks configured here: one for download progress,
+ * and one to decide which tracks to store.
+ *
+ * The default track selection callback will store the largest SD video track.
+ * Provide your own callback to choose the tracks you want to store.
+ *
  * @param {shakaExtern.OfflineConfiguration} config
  * @export
  */
@@ -159,12 +172,21 @@ shaka.offline.Storage.prototype.configure = function(config) {
 
 
 /**
- * Stores the given manifest.
+ * Stores the given manifest.  If the content is encrypted, and encrypted
+ * content cannot be stored on this platform, the Promise will be rejected with
+ * error code 6001, REQUESTED_KEY_SYSTEM_CONFIG_UNAVAILABLE.
  *
- * @param {string} manifestUri
- * @param {!Object} appMetadata
+ * @param {string} manifestUri The URI of the manifest to store.
+ * @param {!Object} appMetadata An arbitrary object from the application that
+ *   will be stored along-side the offline content.  Use this for any
+ *   application-specific metadata you need associated with the stored content.
+ *   For details on the data types that can be stored here, please refer to
+ *   https://goo.gl/h62coS
  * @param {!shakaExtern.ManifestParser.Factory=} opt_manifestParserFactory
- * @return {!Promise.<shakaExtern.StoredContent>}
+ * @return {!Promise.<shakaExtern.StoredContent>}  A Promise to a structure
+ *   representing what was stored.  The "offlineUri" member is the URI that
+ *   should be given to Player.load() to play this piece of content offline.
+ *   The "appMetadata" member is the appMetadata argument you passed to store().
  * @export
  */
 shaka.offline.Storage.prototype.store = function(
@@ -339,7 +361,11 @@ shaka.offline.Storage.prototype.remove = function(content) {
 /**
  * Lists all the stored content available.
  *
- * @return {!Promise.<!Array.<shakaExtern.StoredContent>>}
+ * @return {!Promise.<!Array.<shakaExtern.StoredContent>>}  A Promise to an
+ *   array of structures representing all stored content.  The "offlineUri"
+ *   member of the structure is the URI that should be given to Player.load()
+ *   to play this piece of content offline.  The "appMetadata" member is the
+ *   appMetadata argument you passed to store().
  * @export
  */
 shaka.offline.Storage.prototype.list = function() {