Expand comments on line numbers and blocks.

Reorder compiler_set_lineno() call for consistency.

diff --git a/Python/compile.c b/Python/compile.c
index 1217c1e6aa88a88ce946533263486a642769140e..d4fb638b4efa082d5c75c728958c9b38c97262d8 100644 (file)
--- a/Python/compile.c
+++ b/Python/compile.c
@@ -58,8 +58,9 @@ struct instr {
 };
 
 typedef struct basicblock_ {
-       /* next block in the list of blocks for a unit (don't confuse with
-        * b_next) */
+    /* Each basicblock in a compilation unit is linked via b_list in the
+       reverse order that the block are allocated.  b_list points to the next
+       block, not to be confused with b_next, which is next by control flow. */
        struct basicblock_ *b_list;
        /* number of instructions used */
        int b_iused;
@@ -114,7 +115,9 @@ struct compiler_unit {
        PyObject *u_private;    /* for private name mangling */
 
        int u_argcount;    /* number of arguments for block */ 
-       basicblock *u_blocks; /* pointer to list of blocks */
+    /* Pointer to the most recently allocated block.  By following b_list
+       members, you can reach all early allocated blocks. */
+       basicblock *u_blocks;
        basicblock *u_curblock; /* pointer to current block */
        int u_tmpname;     /* temporary variables for list comps */
 
@@ -1194,7 +1197,7 @@ compiler_new_block(struct compiler *c)
                return NULL;
        }
        memset((void *)b, 0, sizeof(basicblock));
-       assert (b->b_next == NULL);
+    /* Extend the singly linked list of blocks with new block. */
        b->b_list = u->u_blocks;
        u->u_blocks = b;
        return b;
@@ -1267,6 +1270,13 @@ compiler_next_instr(struct compiler *c, basicblock *b)
        return b->b_iused++;
 }
 
+/* Set the i_lineno member of the instruction at offse off if the
+   line number for the current expression/statement (?) has not
+   already been set.  If it has been set, the call has no effect.
+
+   Every time a new node is b
+   */
+
 static void
 compiler_set_lineno(struct compiler *c, int off)
 {
@@ -1609,7 +1619,6 @@ compiler_addop_j(struct compiler *c, int opcode, basicblock *b, int absolute)
        off = compiler_next_instr(c, c->u->u_curblock);
        if (off < 0)
                return 0;
-       compiler_set_lineno(c, off);
        i = &c->u->u_curblock->b_instr[off];
        i->i_opcode = opcode;
        i->i_target = b;
@@ -1618,6 +1627,7 @@ compiler_addop_j(struct compiler *c, int opcode, basicblock *b, int absolute)
                i->i_jabs = 1;
        else
                i->i_jrel = 1;
+       compiler_set_lineno(c, off);
        return 1;
 }
 
@@ -2230,7 +2240,7 @@ compiler_while(struct compiler *c, stmt_ty s)
                ADDOP(c, POP_BLOCK);
        }
        compiler_pop_fblock(c, LOOP, loop);
-       if (orelse != NULL)
+       if (orelse != NULL) /* what if orelse is just pass? */
                VISIT_SEQ(c, stmt, s->v.While.orelse);
        compiler_use_next_block(c, end);
 
@@ -2610,8 +2620,10 @@ compiler_visit_stmt(struct compiler *c, stmt_ty s)
 {
        int i, n;
 
+    /* Always assign a lineno to the next instruction for a stmt. */
        c->u->u_lineno = s->lineno;
        c->u->u_lineno_set = false;
+
        switch (s->kind) {
        case FunctionDef_kind:
                return compiler_function(c, s);
@@ -3486,6 +3498,9 @@ compiler_visit_expr(struct compiler *c, expr_ty e)
 {
        int i, n;
 
+    /* If expr e has a different line number than the last expr/stmt,
+       set a new line number for the next instruction.
+       */
        if (e->lineno > c->u->u_lineno) {
                c->u->u_lineno = e->lineno;
                c->u->u_lineno_set = false;