Document that overlapping spans aren't rendered to HTML correctly

Add some mitigation about why this is probably on OK limitation.

PiperOrigin-RevId: 302907940

library/ui/src/main/java/com/google/android/exoplayer2/ui/SpannedToHtmlConverter.java

@@ -50,6 +50,17 @@ import java.util.List;
    * Convert {@code text} into HTML, adding tags and styling to match any styling spans present.
    * Convert {@code text} into HTML, adding tags and styling to match any styling spans present.
    *
    *
    * <p>All textual content is HTML-escaped during the conversion.
    * <p>All textual content is HTML-escaped during the conversion.
+   *
+   * <p>NOTE: The current implementation does not handle overlapping spans correctly, it will
+   * generate overlapping HTML tags that are invalid. In most cases this won't be a problem because:
+   *
+   * <ul>
+   *   <li>Most subtitle formats use a tagged structure to carry formatting information (e.g. WebVTT
+   *       and TTML), so the {@link Spanned} objects created by these decoders likely won't have
+   *       overlapping spans.
+   *   <li>WebView/Chromium (the intended destination of this HTML) gracefully handles overlapping
+   *       tags and usually renders the same result as spanned text in a TextView.
+   * </ul>
    */
    */
   public static String convert(@Nullable CharSequence text) {
   public static String convert(@Nullable CharSequence text) {
     if (text == null) {
     if (text == null) {

library/ui/src/test/java/com/google/android/exoplayer2/ui/SpannedToHtmlConverterTest.java

@@ -195,4 +195,23 @@ public class SpannedToHtmlConverterTest {
 
 
     assertThat(html).isEqualTo("String with <i>italic and <b>bold</b></i> section");
     assertThat(html).isEqualTo("String with <i>italic and <b>bold</b></i> section");
   }
   }
+
+  @Test
+  public void convert_overlappingSpans_producesInvalidHtml() {
+    SpannableString spanned = new SpannableString("String with italic and bold section");
+    spanned.setSpan(
+        new StyleSpan(Typeface.ITALIC),
+        0,
+        "String with italic and bold".length(),
+        Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
+    spanned.setSpan(
+        new StyleSpan(Typeface.BOLD),
+        "String with italic ".length(),
+        "String with italic and bold section".length(),
+        Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
+
+    String html = SpannedToHtmlConverter.convert(spanned);
+
+    assertThat(html).isEqualTo("<i>String with italic <b>and bold</i> section</b>");
+  }
 }
 }