Cleanups: doc comments, debugging, fix type name collision (#10)

* docs: Add some doc comments + fix typo.
* debug: Make LocalOccurrence debug output clearer
* cleanup: Fix accidental type name collision

Author: varungandhi-src

cfg/Instructions.cc

@@ -312,8 +312,8 @@ string TAbsurd::showRaw(const core::GlobalState &gs, const CFG &cfg, int tabs) c
                        this->what.showRaw(gs, cfg, tabs + 1));
 }
 
-string LocalOccurrence::toString(const core::GlobalState &gs, core::FileRef file, const CFG &cfg) const {
-    return fmt::format("local_occ {} @ {}", this->variable.toString(gs, cfg), core::Loc(file, this->loc).toString(gs));
+string LocalOccurrence::showRaw(const core::GlobalState &gs, core::FileRef file, const CFG &cfg) const {
+    return fmt::format("local_occ {} @ {}", this->variable.toString(gs, cfg), core::Loc(file, this->loc).showRaw(gs));
 }
 
 string VariableUseSite::toString(const core::GlobalState &gs, const CFG &cfg) const {

cfg/Instructions.h

@@ -24,7 +24,7 @@ struct LocalOccurrence final {
         return {variable, core::LocOffsets::none()};
     }
 
-    std::string toString(const core::GlobalState &gs, core::FileRef file, const CFG &cfg) const;
+    std::string showRaw(const core::GlobalState &gs, core::FileRef file, const CFG &cfg) const;
 };
 
 class VariableUseSite final {

scip_indexer/SCIPIndexer.cc

@@ -115,7 +115,7 @@ static bool isTemporary(const core::GlobalState &gs, const core::LocalVariable &
            n == Names::unconditional();
 }
 
-struct LocalOccurrence {
+struct OwnedLocal {
     /// Parent method.
     const core::SymbolRef owner;
     /// Counter corresponding to the local's definition, unique within a method.
@@ -272,7 +272,7 @@ class SCIPState {
     }
 
 public:
-    absl::Status saveDefinition(const core::GlobalState &gs, core::FileRef file, LocalOccurrence occ) {
+    absl::Status saveDefinition(const core::GlobalState &gs, core::FileRef file, OwnedLocal occ) {
         return this->saveDefinitionImpl(gs, file, occ.toString(gs, file), core::Loc(file, occ.offsets));
     }
 
@@ -296,8 +296,7 @@ class SCIPState {
         return this->saveDefinitionImpl(gs, file, symbolString, occLocStatus.value());
     }
 
-    absl::Status saveReference(const core::GlobalState &gs, core::FileRef file, LocalOccurrence occ,
-                               int32_t symbol_roles) {
+    absl::Status saveReference(const core::GlobalState &gs, core::FileRef file, OwnedLocal occ, int32_t symbol_roles) {
         return this->saveReferenceImpl(gs, file, occ.toString(gs, file), occ.offsets, symbol_roles);
     }
 
@@ -361,6 +360,7 @@ class CFGTraversal final {
     UnorderedMap<const cfg::BasicBlock *, UnorderedMap<cfg::LocalRef, core::Loc>> blockLocals;
     UnorderedMap<cfg::LocalRef, uint32_t> functionLocals;
 
+    // Local variable counter that is reset for every function.
     uint32_t counter = 0;
     SCIPState &scipState;
     core::Context ctx;
@@ -387,6 +387,9 @@ class CFGTraversal final {
         RValue,
     };
 
+    // Emit an occurrence for a local variable if applicable.
+    //
+    // Returns true if an occurrence was emitted.
     bool emitLocalOccurrence(const cfg::CFG &cfg, const cfg::BasicBlock *bb, cfg::LocalOccurrence local,
                              ValueCategory category) {
         auto localRef = local.variable;
@@ -436,10 +439,10 @@ class CFGTraversal final {
         absl::Status status;
         if (isDefinition) {
             status = this->scipState.saveDefinition(this->ctx.state, this->ctx.file,
-                                                    LocalOccurrence{this->ctx.owner, localId, local.loc});
+                                                    OwnedLocal{this->ctx.owner, localId, local.loc});
         } else {
             status = this->scipState.saveReference(this->ctx.state, this->ctx.file,
-                                                   LocalOccurrence{this->ctx.owner, localId, local.loc}, referenceRole);
+                                                   OwnedLocal{this->ctx.owner, localId, local.loc}, referenceRole);
         }
         ENFORCE_NO_TIMER(status.ok());
         return true;
@@ -550,7 +553,7 @@ class CFGTraversal final {
                         // Emit references for arguments
                         for (auto &arg : send->args) {
                             // NOTE: For constructs like a += b, the instruction sequence ends up being:
-                            //   $tmp = $b
+                            //   $tmp = $a
                             //   $a = $tmp.+($b)
                             // The location for $tmp will point to $a in the source. However, the second one is a read,
                             // and the first one is a write. Instead of emitting two occurrences, it'd be nice to emit