cmMakefile: Clarify purpose of method that pops a scope snapshot

The `PopPolicyBarrier` method is actually responsible for closing any
scope opened by creating a snapshot.  Rename it to `PopSnapshot` and add
a comment explaining the purpose of the poilcy-scope-specific part of
the method.

2 files changed, 11 insertions, 8 deletions

diff --git a/Source/cmMakefile.cxx b/Source/cmMakefile.cxx
index cb66a75..2c05628 100644
--- a/Source/cmMakefile.cxx
+++ b/Source/cmMakefile.cxx
@@ -435,7 +435,7 @@ cmMakefile::IncludeScope::~IncludeScope()
       this->EnforceCMP0011();
       }
     }
-  this->Makefile->PopPolicyBarrier(this->ReportError);
+  this->Makefile->PopSnapshot(this->ReportError);
 
   this->Makefile->PopFunctionBlockerBarrier(this->ReportError);
 }
@@ -549,7 +549,7 @@ public:
 
   ~ListFileScope()
   {
-    this->Makefile->PopPolicyBarrier(this->ReportError);
+    this->Makefile->PopSnapshot(this->ReportError);
     this->Makefile->PopFunctionBlockerBarrier(this->ReportError);
   }
 
@@ -1551,7 +1551,7 @@ void cmMakefile::PopFunctionScope(bool reportError)
 {
   this->PopPolicy();
 
-  this->PopPolicyBarrier(reportError);
+  this->PopSnapshot(reportError);
 
   this->PopFunctionBlockerBarrier(reportError);
 
@@ -1582,7 +1582,7 @@ void cmMakefile::PushMacroScope(std::string const& fileName,
 void cmMakefile::PopMacroScope(bool reportError)
 {
   this->PopPolicy();
-  this->PopPolicyBarrier(reportError);
+  this->PopSnapshot(reportError);
 
   this->PopFunctionBlockerBarrier(reportError);
 }
@@ -1619,7 +1619,7 @@ public:
   ~BuildsystemFileScope()
   {
     this->Makefile->PopFunctionBlockerBarrier(this->ReportError);
-    this->Makefile->PopPolicyBarrier(this->ReportError);
+    this->Makefile->PopSnapshot(this->ReportError);
 #if defined(CMAKE_BUILD_WITH_CMAKE)
     this->GG->GetFileLockPool().PopFileScope();
 #endif
@@ -4614,7 +4614,7 @@ cmMakefile::PolicyPushPop::PolicyPushPop(cmMakefile* m, bool weak,
 cmMakefile::PolicyPushPop::~PolicyPushPop()
 {
   this->Makefile->PopPolicy();
-  this->Makefile->PopPolicyBarrier(this->ReportError);
+  this->Makefile->PopSnapshot(this->ReportError);
 }
 
 //----------------------------------------------------------------------------
@@ -4634,8 +4634,11 @@ void cmMakefile::PopPolicy()
 }
 
 //----------------------------------------------------------------------------
-void cmMakefile::PopPolicyBarrier(bool reportError)
+void cmMakefile::PopSnapshot(bool reportError)
 {
+  // cmState::Snapshot manages nested policy scopes within it.
+  // Since the scope corresponding to the snapshot is closing,
+  // reject any still-open nested policy scopes with an error.
   while (!this->StateSnapshot.CanPopPolicyScope())
     {
     if(reportError)
diff --git a/Source/cmMakefile.h b/Source/cmMakefile.h
index 111f074..a112d57 100644
--- a/Source/cmMakefile.h
+++ b/Source/cmMakefile.h
@@ -904,7 +904,7 @@ private:
   void PushPolicy(bool weak = false,
                   cmPolicies::PolicyMap const& pm = cmPolicies::PolicyMap());
   void PopPolicy();
-  void PopPolicyBarrier(bool reportError = true);
+  void PopSnapshot(bool reportError = true);
   friend class cmCMakePolicyCommand;
   class IncludeScope;
   friend class IncludeScope;