From 7872affa9689284eb02f019b6bf1900cf7d921e5 Mon Sep 17 00:00:00 2001
From: Jean-Michel Trivi <jmtrivi@google.com>
Date: Wed, 6 Jul 2016 14:34:52 -0700
Subject: [PATCH] More javadoc for audio recording activity API

Better overview of feature inside AudioRecordingConfiguration
 class description.
Addition of @see links in AudioManager query and callback methods.

Bug 27929523

Change-Id: I9159ffd40d68f7c65f59570119821087643f9030
---
 media/java/android/media/AudioManager.java       |  2 ++
 .../media/AudioRecordingConfiguration.java       | 16 +++++++++++++---
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/media/java/android/media/AudioManager.java b/media/java/android/media/AudioManager.java
index 4bdc70e376218..f19a2624457e2 100644
--- a/media/java/android/media/AudioManager.java
+++ b/media/java/android/media/AudioManager.java
@@ -2744,6 +2744,7 @@ public class AudioManager {
      * to be notified.
      * Use {@link AudioManager#getActiveRecordingConfigurations()} to query the current
      * configuration.
+     * @see AudioRecordingConfiguration
      */
     public static abstract class AudioRecordingCallback {
         /**
@@ -2850,6 +2851,7 @@ public class AudioManager {
      * Returns the current active audio recording configurations of the device.
      * @return a non-null list of recording configurations. An empty list indicates there is
      *     no recording active when queried.
+     * @see AudioRecordingConfiguration
      */
     public @NonNull List<AudioRecordingConfiguration> getActiveRecordingConfigurations() {
         final IAudioService service = getService();
diff --git a/media/java/android/media/AudioRecordingConfiguration.java b/media/java/android/media/AudioRecordingConfiguration.java
index 593516639e29a..354339c545a4a 100644
--- a/media/java/android/media/AudioRecordingConfiguration.java
+++ b/media/java/android/media/AudioRecordingConfiguration.java
@@ -28,8 +28,18 @@ import java.util.Objects;
 
 /**
  * The AudioRecordingConfiguration class collects the information describing an audio recording
- * session. This information is returned through the
- * {@link AudioManager#getActiveRecordingConfigurations()} method.
+ * session.
+ * <p>Direct polling (see {@link AudioManager#getActiveRecordingConfigurations()}) or callback
+ * (see {@link AudioManager#registerAudioRecordingCallback(android.media.AudioManager.AudioRecordingCallback, android.os.Handler)}
+ * methods are ways to receive information about the current recording configuration of the device.
+ * <p>An audio recording configuration contains information about the recording format as used by
+ * the application ({@link #getClientFormat()}, as well as the recording format actually used by
+ * the device ({@link #getFormat()}). The two recording formats may, for instance, be at different
+ * sampling rates due to hardware limitations (e.g. application recording at 44.1kHz whereas the
+ * device always records at 48kHz, and the Android framework resamples for the application).
+ * <p>The configuration also contains the use case for which audio is recorded
+ * ({@link #getClientAudioSource()}), enabling the ability to distinguish between different
+ * activities such as ongoing voice recognition or camcorder recording.
  *
  */
 public final class AudioRecordingConfiguration implements Parcelable {
@@ -198,4 +208,4 @@ public final class AudioRecordingConfiguration implements Parcelable {
                 && (mClientFormat.equals(that.mClientFormat))
                 && (mDeviceFormat.equals(that.mDeviceFormat)));
     }
-}
\ No newline at end of file
+}