From ca7bf64c94591f4994988359733e2f2fb02f0ca3 Mon Sep 17 00:00:00 2001
From: Jean-Michel Trivi <jmtrivi@google.com>
Date: Mon, 18 Oct 2021 17:26:16 -0700
Subject: [PATCH] AudioMixingRule: more javadoc on mix role

Bug: 194163617
Test: make doc-comment-check-docs
Change-Id: I562b06e1698264c3abfe11076f4e125284c79f54
---
 .../media/audiopolicy/AudioMixingRule.java     | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/media/java/android/media/audiopolicy/AudioMixingRule.java b/media/java/android/media/audiopolicy/AudioMixingRule.java
index fa3dc7211dea0..611229080e4c6 100644
--- a/media/java/android/media/audiopolicy/AudioMixingRule.java
+++ b/media/java/android/media/audiopolicy/AudioMixingRule.java
@@ -504,8 +504,22 @@ public class AudioMixingRule {
         /**
          * Sets target mix role of the mixing rule.
          *
-         * <p>The mix role indicates playback streams will be captured or recording source will be
-         * injected. If not specified, the mix role will be decided automatically when
+         * As each mixing rule is intended to be associated with an {@link AudioMix},
+         * explicitly setting the role of a mixing rule allows this {@link Builder} to
+         * verify validity of the mixing rules to be validated.<br>
+         * The mix role allows distinguishing between:
+         * <ul>
+         * <li>audio framework mixers that will mix / sample-rate convert / reformat the audio
+         *     signal of any audio player (e.g. a {@link android.media.MediaPlayer}) that matches
+         *     the selection rules defined in the object being built. Use
+         *     {@link AudioMixingRule#MIX_ROLE_PLAYERS} for such an {@code AudioMixingRule}</li>
+         * <li>audio framework mixers that will be used as the injection point (after sample-rate
+         *     conversion and reformatting of the audio signal) into any audio recorder (e.g. a
+         *     {@link android.media.AudioRecord}) that matches the selection rule defined in the
+         *     object being built. Use {@link AudioMixingRule#MIX_ROLE_INJECTOR} for such an
+         *     {@code AudioMixingRule}.</li>
+         * </ul>
+         * <p>If not specified, the mix role will be decided automatically when
          * {@link #addRule(AudioAttributes, int)} or {@link #addMixRule(int, Object)} be called.
          *
          * @param mixRole integer value of {@link #MIX_ROLE_PLAYERS} or {@link #MIX_ROLE_INJECTOR}