[code-health] Improve a comment

Bug: v8:7754
Change-Id: Ifa329efa1ccbae3d4cf6251f43b11b697ddf76f8
Reviewed-on: https://chromium-review.googlesource.com/1068678
Commit-Queue: Sigurd Schneider <sigurds@chromium.org>
Reviewed-by: Tobias Tebbi <tebbi@chromium.org>
Cr-Commit-Position: refs/heads/master@{#53321}

src/torque/contextual.h

@@ -7,17 +7,27 @@
 
 #include <type_traits>
 
+#include "src/base/macros.h"
+#include "src/base/platform/platform.h"
+
 namespace v8 {
 namespace internal {
 namespace torque {
 
-// Contextual variables store a value in one or more stack-allocated scopes and
-// allow global access to the most recent active scope on the current
-// call-stack.
+// {ContextualVariable} provides a clean alternative to a global variable.
+// The contextual variable is mutable, and supports managing the value of
+// a variable in a well-nested fashion via the {Scope} class.
+// {ContextualVariable} only stores a pointer to the current value, which
+// is stored in a {Scope} object. The most recent value can be retrieved
+// via Get(). Because only {Scope} has actual storage, there must be at
+// least one active {Scope} (i.e. in a surrounding C++ scope), whenever Get()
+// is called.
+// Note that contextual variables must only be used from the same thread,
+// i.e. {Scope} and Get() have to be in the same thread.
 template <class Derived, class VarType>
 class ContextualVariable {
  public:
-  // A {Scope} contains a new object of type {T} and gives
+  // A {Scope} contains a new object of type {VarType} and gives
   // ContextualVariable::Get() access to it. Upon destruction, the contextual
   // variable is restored to the state before the {Scope} was created. Scopes
   // have to follow a stack discipline:  A {Scope} has to be destructed before
@@ -40,6 +50,9 @@ class ContextualVariable {
 
     static_assert(std::is_base_of<ContextualVariable, Derived>::value,
                   "Curiously Recurring Template Pattern");
+
+    DISALLOW_NEW_AND_DELETE();
+    DISALLOW_COPY_AND_ASSIGN(Scope);
   };
 
   // Access the most recent active {Scope}. There has to be an active {Scope}
@@ -62,7 +75,7 @@ thread_local VarType* ContextualVariable<Derived, VarType>::top_ = nullptr;
       : v8::internal::torque::ContextualVariable<VarName, __VA_ARGS__> {};
 
 // By inheriting from {ContextualClass} a class can become a contextual variable
-// of itself.
+// of itself, which is very similar to a singleton.
 template <class T>
 using ContextualClass = ContextualVariable<T, T>;
 

third_party/antlr4/runtime/Cpp/runtime/src/atn/ATNSimulator.cpp

@@ -15,7 +15,8 @@ using namespace antlr4;
 using namespace antlr4::dfa;
 using namespace antlr4::atn;
 
-const Ref<DFAState> ATNSimulator::ERROR = std::make_shared<DFAState>(INT32_MAX);
+const Ref<DFAState> ATNSimulator::ERROR_STATE =
+    std::make_shared<DFAState>(INT32_MAX);
 antlrcpp::SingleWriteMultipleReadLock ATNSimulator::_stateLock;
 antlrcpp::SingleWriteMultipleReadLock ATNSimulator::_edgeLock;
 

third_party/antlr4/runtime/Cpp/runtime/src/atn/ATNSimulator.h

@@ -16,7 +16,7 @@ namespace atn {
 class ANTLR4CPP_PUBLIC ATNSimulator {
  public:
   /// Must distinguish between missing edge and edge we know leads nowhere.
-  static const Ref<dfa::DFAState> ERROR;
+  static const Ref<dfa::DFAState> ERROR_STATE;
   const ATN& atn;
 
   ATNSimulator(const ATN& atn, PredictionContextCache& sharedContextCache);

third_party/antlr4/runtime/Cpp/runtime/src/atn/LexerATNSimulator.cpp

@@ -155,7 +155,7 @@ size_t LexerATNSimulator::execATN(CharStream* input, dfa::DFAState* ds0) {
       target = computeTargetState(input, s, t);
     }
 
-    if (target == ERROR.get()) {
+    if (target == ERROR_STATE.get()) {
       break;
     }
 
@@ -217,11 +217,11 @@ dfa::DFAState* LexerATNSimulator::computeTargetState(CharStream* input,
       // we got nowhere on t, don't throw out this knowledge; it'd
       // cause a failover from DFA later.
       delete reach;
-      addDFAEdge(s, t, ERROR.get());
+      addDFAEdge(s, t, ERROR_STATE.get());
     }
 
     // stop when we can't match any more char
-    return ERROR.get();
+    return ERROR_STATE.get();
   }
 
   // Add an edge from s to target DFA found/created for reach

third_party/antlr4/runtime/Cpp/runtime/src/atn/ParserATNSimulator.cpp

@@ -183,7 +183,7 @@ size_t ParserATNSimulator::execATN(dfa::DFA& dfa, dfa::DFAState* s0,
       D = computeTargetState(dfa, previousD, t);
     }
 
-    if (D == ERROR.get()) {
+    if (D == ERROR_STATE.get()) {
       // if any configs in previous dipped into outer context, that
       // means that input up to t actually finished entry rule
       // at least for SLL decision. Full LL doesn't dip into outer
@@ -299,8 +299,8 @@ dfa::DFAState* ParserATNSimulator::computeTargetState(dfa::DFA& dfa,
   std::unique_ptr<ATNConfigSet> reach =
       computeReachSet(previousD->configs.get(), t, false);
   if (reach == nullptr) {
-    addDFAEdge(dfa, previousD, t, ERROR.get());
-    return ERROR.get();
+    addDFAEdge(dfa, previousD, t, ERROR_STATE.get());
+    return ERROR_STATE.get();
   }
 
   // create new target state; we'll add to DFA after it's complete
@@ -1409,7 +1409,7 @@ dfa::DFAState* ParserATNSimulator::addDFAEdge(dfa::DFA& dfa,
 
 dfa::DFAState* ParserATNSimulator::addDFAState(dfa::DFA& dfa,
                                                dfa::DFAState* D) {
-  if (D == ERROR.get()) {
+  if (D == ERROR_STATE.get()) {
     return D;
   }
 

third_party/antlr4/runtime/Cpp/runtime/src/atn/ProfilingATNSimulator.cpp

@@ -90,7 +90,7 @@ DFAState* ProfilingATNSimulator::getExistingTargetState(DFAState* previousD,
   if (existingTargetState != nullptr) {
     _decisions[_currentDecision]
         .SLL_DFATransitions++;  // count only if we transition over a DFA state
-    if (existingTargetState == ERROR.get()) {
+    if (existingTargetState == ERROR_STATE.get()) {
       _decisions[_currentDecision].errors.push_back(
           ErrorInfo(_currentDecision, previousD->configs.get(), _input,
                     _startIndex, _sllStopIndex, false));