Comment improvements.

tools/trace-malloc/bloatblame.c

@@ -256,8 +256,8 @@ static void connect_nodes(graphnode *from, graphnode *to, callsite *site)
             /*
              * Say the stack looks like this: ... => JS => js => JS => js.
              * We must avoid overcounting JS=>js because the first edge total
-             * includes second (because the lower site's total includes all
-             * its kids' totals).
+             * includes the second JS=>js edge's total (which is because the
+             * lower site's total includes all its kids' totals).
              */
             if (!to->low || to->low < from->low) {
                 edge[0].direct += site->direct;

tools/trace-malloc/lib/nsTraceMalloc.h

@@ -43,8 +43,9 @@ PR_BEGIN_EXTERN_C
 
 /**
  * Call NS_TraceMalloc with a valid log file descriptor to enable logging
- * of compressed malloc traces, including callsite chains.  Integers are
- * unsigned, at most 32 bits, and encoded as follows:
+ * of compressed malloc traces, including callsite chains.  Integers may be
+ * unsigned serial numbers, sizes, or offsets, and require at most 32 bits.
+ * They're encoded as follows:
  *   0-127                  0xxxxxxx (binary, one byte)
  *   128-16383              10xxxxxx xxxxxxxx
  *   16384-0x1fffff         110xxxxx xxxxxxxx xxxxxxxx

xpcom/base/bloatblame.c

@@ -256,8 +256,8 @@ static void connect_nodes(graphnode *from, graphnode *to, callsite *site)
             /*
              * Say the stack looks like this: ... => JS => js => JS => js.
              * We must avoid overcounting JS=>js because the first edge total
-             * includes second (because the lower site's total includes all
-             * its kids' totals).
+             * includes the second JS=>js edge's total (which is because the
+             * lower site's total includes all its kids' totals).
              */
             if (!to->low || to->low < from->low) {
                 edge[0].direct += site->direct;

xpcom/base/nsTraceMalloc.h

@@ -43,8 +43,9 @@ PR_BEGIN_EXTERN_C
 
 /**
  * Call NS_TraceMalloc with a valid log file descriptor to enable logging
- * of compressed malloc traces, including callsite chains.  Integers are
- * unsigned, at most 32 bits, and encoded as follows:
+ * of compressed malloc traces, including callsite chains.  Integers may be
+ * unsigned serial numbers, sizes, or offsets, and require at most 32 bits.
+ * They're encoded as follows:
  *   0-127                  0xxxxxxx (binary, one byte)
  *   128-16383              10xxxxxx xxxxxxxx
  *   16384-0x1fffff         110xxxxx xxxxxxxx xxxxxxxx