From c468240c1a2a393ec02d992f459c6586ae450161 Mon Sep 17 00:00:00 2001
From: Scott Main <smain@google.com>
Date: Thu, 13 Jun 2013 12:38:55 -0700
Subject: [PATCH] Revised some text while reading up on traceview. this is
 what's left of this older CL that was left for dead:
 I5528b476d8110df51d45aaf690d878f72bc75c9f

Change-Id: I42f784d693c0a2a2e2e8ed4c582cbc10180191e7
---
 core/java/android/os/Trace.java               |  5 +-
 .../html/tools/debugging/debugging-tracing.jd | 56 ++++++++++---------
 2 files changed, 35 insertions(+), 26 deletions(-)

diff --git a/core/java/android/os/Trace.java b/core/java/android/os/Trace.java
index bb3d296acd799..3249bcb517433 100644
--- a/core/java/android/os/Trace.java
+++ b/core/java/android/os/Trace.java
@@ -22,9 +22,12 @@ import android.util.Log;
  * Writes trace events to the system trace buffer.  These trace events can be
  * collected and visualized using the Systrace tool.
  *
- * This tracing mechanism is independent of the method tracing mechanism
+ * <p>This tracing mechanism is independent of the method tracing mechanism
  * offered by {@link Debug#startMethodTracing}.  In particular, it enables
  * tracing of events that occur across multiple processes.
+ * <p>For information about using the Systrace tool, read <a
+ * href="{@docRoot}tools/debugging/systrace.html">Analyzing Display and Performance
+ * with Systrace</a>.
  */
 public final class Trace {
     /*
diff --git a/docs/html/tools/debugging/debugging-tracing.jd b/docs/html/tools/debugging/debugging-tracing.jd
index 8653da664ba1e..bd4afbcc1de11 100644
--- a/docs/html/tools/debugging/debugging-tracing.jd
+++ b/docs/html/tools/debugging/debugging-tracing.jd
@@ -38,8 +38,7 @@ parent.link=index.html
   <h2 id="traceviewLayout">Traceview Layout</h2>
 
   <p>When you have a trace log file (generated by adding tracing code to your application or by DDMS),
-  you can have Traceview load the log files and display their data in a window visualizes your application
-  in two panels:</p>
+  you can load the log files in Traceview, which displays the log data in two panels:</p>
 
   <ul>
     <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread and method
@@ -53,12 +52,11 @@ parent.link=index.html
   
   <h3 id="timelinepanel">Timeline Panel</h3>
 
-  <p>The image below shows a close up of the timeline panel. Each thread&rsquo;s execution is shown
+  <p>Figure 1 shows a close up of the timeline panel. Each thread&rsquo;s execution is shown
   in its own row, with time increasing to the right. Each method is shown in another color (colors
   are reused in a round-robin fashion starting with the methods that have the most inclusive time).
   The thin lines underneath the first row show the extent (entry to exit) of all the calls to the
-  selected method. The method in this case is <code>LoadListener.nativeFinished()</code> and it was selected in
-  the profile view.</p>
+  selected method.</p>
 
   <img src="{@docRoot}images/traceview_timeline.png"
        alt="Traceview timeline panel"
@@ -94,23 +92,31 @@ parent.link=index.html
   <p>There are two ways to generate trace logs:</p>
   <ul>
     <li>Include the {@link android.os.Debug} class in your code and call its
-  methods to start and stop logging of trace information to disk. This method is very precise because
-  you can specify in your code exactly where to start and stop logging trace data.</li>
-    <li>Use the method profiling feature of DDMS to generate trace logs. This method is less
-    precise since you do not modify code, but rather specify when to start and stop logging with
-    a DDMS. Although you have less control on exactly where the data is logged, this method is useful 
-    if you don't have access to the application's code, or if you do not need the precision of the first method.
+  methods such as {@link android.os.Debug#startMethodTracing()} and {@link
+  android.os.Debug#stopMethodTracing()}, to start and stop logging of trace information to disk.
+  This option is very precise because
+  you can specify exactly where to start and stop logging trace data in your code.</li>
+    <li>Use the method profiling feature of DDMS to generate trace logs. This option is less
+    precise because you do not modify code, but rather specify when to start and stop logging with
+    DDMS. Although you have less control on exactly where logging starts and stops,
+    this option is useful if you don't have access to the application's code, or if you do
+    not need precise log timing.
     </li>
   </ul>
   
   <p>Before you start generating trace logs, be aware of the following restrictions:</p>
   <ul>
-    <li>If you are using the {@link android.os.Debug} class, your device or emulator must have an SD card
-     and your application must have permission to write to the SD card. </li>
-    <li>If you are using DDMS, Android 2.1 and earlier devices must
+    <li>If you are using the {@link android.os.Debug} class,
+     your application must have permission to write to external storage
+     ({@link android.Manifest.permission#READ_EXTERNAL_STORAGE}). </li>
+    <li>If you are using DDMS:
+      <ul>
+        <li>Android 2.1 and earlier devices must
     have an SD card present and your application must have permission to write to the SD card.
-    <li>If you are using DDMS, Android 2.2 and later devices do not need an SD card. The trace log files are 
+        <li>Android 2.2 and later devices do not need an SD card. The trace log files are
     streamed directly to your development machine.</li>
+      </ul>
+    </li>
   </ul>
   
   <p>This document focuses on using the {@link android.os.Debug} class to generate trace data.  For more information on using DDMS
@@ -134,22 +140,22 @@ parent.link=index.html
     Debug.stopMethodTracing();
 </pre>
 
-  <p>When your application calls startMethodTracing(), the system creates a file called
+  <p>When your application calls {@link android.os.Debug#startMethodTracing() startMethodTracing()},
+  the system creates a file called
   <code>&lt;trace-base-name&gt;.trace</code>. This contains the binary method trace data and a
   mapping table with thread and method names.</p>
 
   <p>The system then begins buffering the generated trace data, until your application calls
-  stopMethodTracing(), at which time it writes the buffered data to the output file. If the system
-  reaches the maximum buffer size before stopMethodTracing() is called, the system stops tracing
+  {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}, at which time it writes
+  the buffered data to the output file. If the system
+  reaches the maximum buffer size before you call {@link android.os.Debug#stopMethodTracing()
+  stopMethodTracing()}, the system stops tracing
   and sends a notification to the console.</p>
 
-  <p>Interpreted code will run more slowly when profiling is enabled. Don't try to generate
-  absolute timings from the profiler results (i.e. "function X takes 2.5 seconds to run"). The
+  <p>Interpreted code runs more slowly when profiling is enabled. Don't try to generate
+  absolute timings from the profiler results (such as, "function X takes 2.5 seconds to run"). The
   times are only useful in relation to other profile output, so you can see if changes have made
-  the code faster or slower.</p>
-
-  <p>When using the Android emulator, you must specify an SD card when you create your AVD because the trace files
-  are written to the SD card. Your application must have permission to write to the SD card as well.
+  the code faster or slower relative to a previous profiling run.</p>
 
   <h2 id="copyingfiles">Copying Trace Files to a Host Machine</h2>
 
@@ -189,7 +195,7 @@ traceview /tmp/calc
       "{@docRoot}images/tracedump.png"
           width="485"
           height="401" />
-       <p class="image-caption"><strong>Figure 3.</strong> Screenshot of dmtracedump</p>
+       <p class="img-caption"><strong>Figure 3.</strong> Screenshot of dmtracedump</p>
 
       <p>For each node, dmtracedump shows <code>&lt;ref&gt;
       <em>callname</em> (&lt;inc-ms&gt;, &lt;exc-ms&gt;,&lt;numcalls&gt;)</code>, where</p>