Add comments for AlteredTableInfo->rel

The prior commit which introduced it was pretty squalid in terms of
code documentation, so add some comments.

diff --git a/src/backend/commands/tablecmds.c b/src/backend/commands/tablecmds.c
index bf7fd6e8ae665d94f8664a181599a819a1c8eadd..550b84681e498b547ece7096133a7aec974cf61c 100644 (file)
--- a/src/backend/commands/tablecmds.c
+++ b/src/backend/commands/tablecmds.c
@@ -157,8 +157,16 @@ typedef struct AlteredTableInfo
    Oid         relid;          /* Relation to work on */
    char        relkind;        /* Its relkind */
    TupleDesc   oldDesc;        /* Pre-modification tuple descriptor */
-   /* Transiently set during Phase 2, normally set to NULL */
+
+   /*
+    * Transiently set during Phase 2, normally set to NULL.
+    *
+    * ATRewriteCatalogs sets this when it starts, and closes when ATExecCmd
+    * returns control.  This can be exploited by ATExecCmd subroutines to
+    * close/reopen across transaction boundaries.
+    */
    Relation    rel;
+
    /* Information saved by Phase 1 for Phase 2: */
    List       *subcmds[AT_NUM_PASSES]; /* Lists of AlterTableCmd */
    /* Information saved by Phases 1/2 for Phase 3: */
@@ -4577,7 +4585,9 @@ ATRewriteCatalogs(List **wqueue, LOCKMODE lockmode,
                continue;
 
            /*
-            * Appropriate lock was obtained by phase 1, needn't get it again
+            * Open the relation and store it in tab.  This allows subroutines
+            * close and reopen, if necessary.  Appropriate lock was obtained
+            * by phase 1, needn't get it again.
             */
            tab->rel = relation_open(tab->relid, NoLock);