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);