From ff42a9938bb7e459fd48c875a327709b8e4e4fd3 Mon Sep 17 00:00:00 2001
From: Jonathan Lepage <jol@google.com>
Date: Thu, 28 Oct 2021 01:14:26 +0000
Subject: [PATCH] Document that Log can quietly swallow UnknownHostExceptions.

Change-Id: I7d3239eadf7dd73dd1ff12d2924bb43d3e357299
---
 core/java/android/util/Log.java | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/core/java/android/util/Log.java b/core/java/android/util/Log.java
index 12bcd8b0aa977..b5fe4f58dfb29 100644
--- a/core/java/android/util/Log.java
+++ b/core/java/android/util/Log.java
@@ -62,6 +62,10 @@ import java.net.UnknownHostException;
  * another buffer allocation and copy, and even more pressure on the gc.
  * That means that if your log message is filtered out, you might be doing
  * significant work and incurring significant overhead.
+ *
+ * <p>When calling the log methods that take a Throwable parameter,
+ * if any of the throwables in the cause chain is an <code>UnknownHostException</code>,
+ * then the stack trace is not logged.
  */
 public final class Log {
     /** @hide */
@@ -341,6 +345,9 @@ public final class Log {
 
     /**
      * Handy function to get a loggable stack trace from a Throwable
+
+     * <p>If any of the throwables in the cause chain is an <code>UnknownHostException</code>,
+     * this returns an empty string.
      * @param tr An exception to log
      */
     @NonNull