rts: Update some comments, minor refactoring

includes/rts/storage/GC.h

@@ -109,7 +109,12 @@ typedef struct generation_ {
     memcount       n_compact_blocks_in_import; // no. of blocks used by compacts
                                                // being imported
 
-    memcount       max_blocks;          // max blocks
+    // Max blocks to allocate in this generation before collecting it. Collect
+    // this generation when
+    //
+    //     n_blocks + n_large_blocks + n_compact_blocks > max_blocks
+    //
+    memcount       max_blocks;
 
     StgTSO *       threads;             // threads in this gen
                                         // linked via global_link

rts/Capability.h

@@ -109,7 +109,7 @@ struct Capability_ {
     int interrupt;
 
     // Total words allocated by this cap since rts start
-    // See [Note allocation accounting] in Storage.c
+    // See Note [allocation accounting] in Storage.c
     W_ total_allocated;
 
 #if defined(THREADED_RTS)

rts/sm/Storage.c

@@ -1158,7 +1158,7 @@ dirty_MVAR(StgRegTable *reg, StgClosure *p)
  * -------------------------------------------------------------------------- */
 
 /* -----------------------------------------------------------------------------
- * [Note allocation accounting]
+ * Note [allocation accounting]
  *
  *   - When cap->r.rCurrentNusery moves to a new block in the nursery,
  *     we add the size of the used portion of the previous block to
@@ -1271,9 +1271,8 @@ W_ gcThreadLiveBlocks (uint32_t i, uint32_t g)
 extern W_
 calcNeeded (bool force_major, memcount *blocks_needed)
 {
-    W_ needed = 0, blocks;
-    uint32_t g, N;
-    generation *gen;
+    W_ needed = 0;
+    uint32_t N;
 
     if (force_major) {
         N = RtsFlags.GcFlags.generations - 1;
@@ -1281,10 +1280,10 @@ calcNeeded (bool force_major, memcount *blocks_needed)
         N = 0;
     }
 
-    for (g = 0; g < RtsFlags.GcFlags.generations; g++) {
-        gen = &generations[g];
+    for (uint32_t g = 0; g < RtsFlags.GcFlags.generations; g++) {
+        generation *gen = &generations[g];
 
-        blocks = gen->n_blocks // or: gen->n_words / BLOCK_SIZE_W (?)
+        W_ blocks = gen->n_blocks // or: gen->n_words / BLOCK_SIZE_W (?)
                   + gen->n_large_blocks
                   + gen->n_compact_blocks;