Document that release() should be called with onPause() and onStop() for media objects

Change-Id: I12dd734b4314df4f0573ad56a1714348e50da05e
related-to-bug: 5616833

2 files changed, 28 insertions, 9 deletions

diff --git a/media/java/android/media/MediaPlayer.java b/media/java/android/media/MediaPlayer.java
index eb32563..8d71dcf 100644
--- a/media/java/android/media/MediaPlayer.java
+++ b/media/java/android/media/MediaPlayer.java
@@ -1149,14 +1149,20 @@ public class MediaPlayer
     /**
      * Releases resources associated with this MediaPlayer object.
      * It is considered good practice to call this method when you're
-     * done using the MediaPlayer. For instance, whenever the Activity
-     * of an application is paused, this method should be invoked to
-     * release the MediaPlayer object. In addition to unnecessary resources
-     * (such as memory and instances of codecs) being hold, failure to
-     * call this method immediately if a MediaPlayer object is no longer
-     * needed may also lead to continuous battery consumption for mobile
-     * devices, and playback failure if no multiple instances of the
-     * same codec is supported on a device.
+     * done using the MediaPlayer. In particular, whenever an Activity
+     * of an application is paused (its onPause() method is called),
+     * or stopped (its onStop() method is called), this method should be
+     * invoked to release the MediaPlayer object, unless the application
+     * has a special need to keep the object around. In addition to
+     * unnecessary resources (such as memory and instances of codecs)
+     * being held, failure to call this method immediately if a
+     * MediaPlayer object is no longer needed may also lead to
+     * continuous battery consumption for mobile devices, and playback
+     * failure for other applications if no multiple instances of the
+     * same codec are supported on a device. Even if multiple instances
+     * of the same codec are supported, some performance degradation
+     * may be expected when unnecessary multiple instances are used
+     * at the same time.
      */
     public void release() {
         stayAwake(false);
diff --git a/media/java/android/media/MediaRecorder.java b/media/java/android/media/MediaRecorder.java
index ceeacbb..08e6032 100644
--- a/media/java/android/media/MediaRecorder.java
+++ b/media/java/android/media/MediaRecorder.java
@@ -926,7 +926,20 @@ public class MediaRecorder
     /**
      * Releases resources associated with this MediaRecorder object.
      * It is good practice to call this method when you're done
-     * using the MediaRecorder.
+     * using the MediaRecorder. In particular, whenever an Activity
+     * of an application is paused (its onPause() method is called),
+     * or stopped (its onStop() method is called), this method should be
+     * invoked to release the MediaRecorder object, unless the application
+     * has a special need to keep the object around. In addition to
+     * unnecessary resources (such as memory and instances of codecs)
+     * being held, failure to call this method immediately if a
+     * MediaRecorder object is no longer needed may also lead to
+     * continuous battery consumption for mobile devices, and recording
+     * failure for other applications if no multiple instances of the
+     * same codec are supported on a device. Even if multiple instances
+     * of the same codec are supported, some performance degradation
+     * may be expected when unnecessary multiple instances are used
+     * at the same time.
      */
     public native void release();