Bug 1666615 - Update comments for CacheIR health report. r=iain

Differential Revision: https://phabricator.services.mozilla.com/D91347

js/src/jit/CacheIRHealth.h

@@ -18,22 +18,35 @@ namespace jit {
 
 class ICEntry;
 
-// [SMDOC] CacheIR Health Rating
+// [SMDOC] CacheIR Health Report
 //
-// The goal of CacheIR health rating is to make the costlier
+// The goal of CacheIR health report is to make the costlier
 // CacheIR stubs more apparent and easier to diagnose.
 // This is done by using the scores assigned to different CacheIROps in
 // CacheIROps.yaml (see the description of cost_estimate in the
 // aforementioned file for how these scores are determined), summing
 // the score of each op generated for a particular stub together, and displaying
-// this score for each stub in a CacheIR chain. The higher the total stub score
+// this score for each stub in an inline cache. The higher the total stub score,
 // the more expensive the stub is.
 //
-// To see the CacheIR health rating for a script, simply call the
-// rateMyCacheIR() shell function. This function takes either a particular
-// function as a parameter and then prints the health of the CacheIR generated
-// for the script associated with that function, or if you call rateMyCacheIR()
-// without any parameters it will take the topmost script and rate that.
+// There are a few ways to generate a health report for a script:
+// 1. Simply running a JS program with the evironment variable
+//    SPEW=RateMyCacheIR. We generate a health report for a script whenever we
+//    reach the trial inlining threshold.
+//      ex) SPEW=RateMyCacheIR dist/bin/js jsprogram.js
+// 2. In the shell you can call rateMyCacheIR() with no arguments and a report
+//    will be generated for all scripts in the current zone.
+//      ex) rateMyCacheIR()
+// 3. You may also call rateMyCacheIR() on a particular function to see the
+//    health report associated with that function's script.
+//      ex) rateMyCacheIR(foo)
+//
+// Once you have generated a health report, you may go to
+// https://carolinecullen.github.io/cacheirhealthreport/ to visualize the data
+// and aid in understanding what may be going wrong with the CacheIR for a
+// particular stub. For more information about the tool and why a particular
+// script, inline cache entry, or stub is unhappy go to:
+// https://carolinecullen.github.io/cacheirhealthreport/info.html
 //
 
 class CacheIRHealth {
@@ -52,7 +65,7 @@ class CacheIRHealth {
   Happiness spewJSOpAndCacheIRHealth(AutoStructuredSpewer& spew,
                                      HandleScript script, jit::ICEntry* entry,
                                      jsbytecode* pc, JSOp op);
-  // If a JitScript exists, shows health of all ICEntries that exist
+  // If a JitScript exists, spew the health of all ICEntries that exist
   // for the specified script.
   bool rateMyCacheIR(JSContext* cx, HandleScript script);
 };