Repository: carbon-language/carbon-lang
File: toolchain/check/context.h (C/C++)

Code before:
  // remain const.
  auto SetNamespaceNodeId(SemIR::InstId inst_id, Parse::NodeId node_id)
      -> void {
    sem_ir().insts().SetLocId(inst_id, SemIR::LocId(node_id));
  }

  // Adds a name to name lookup. Prints a diagnostic for name conflicts.
  auto AddNameToLookup(SemIR::NameId name_id, SemIR::InstId target_id) -> void;

  // Performs name lookup in a specified scope for a name appearing in a
  // declaration. If found, returns the referenced instruction and false. If
  // poisoned, returns invalid instructions and true. poisoned. If scope_id is
  // invalid, uses the current contextual scope.
  // TODO: For poisoned names, return the poisoning instruction.
  auto LookupNameInDecl(SemIR::LocId loc_id, SemIR::NameId name_id,
                        SemIR::NameScopeId scope_id)
      -> std::pair<SemIR::InstId, bool>;

  // Performs an unqualified name lookup, returning the referenced instruction.
  auto LookupUnqualifiedName(Parse::NodeId node_id, SemIR::NameId name_id,
                             bool required = true) -> LookupResult;

  struct LookupNameInExactScopeResult {
    SemIR::InstId inst_id;
    SemIR::AccessKind access_kind;
    bool is_poisoned = false;
  };

  // Performs a name lookup in a specified scope, returning the referenced
  // instruction. Does not look into extended scopes. Returns an invalid
  // instruction if the name is not found or poisoned.
  // TODO: Return the poisoning instruction if poisoned.
  auto LookupNameInExactScope(SemIRLoc loc, SemIR::NameId name_id,
                              SemIR::NameScopeId scope_id,
                              const SemIR::NameScope& scope)
      -> LookupNameInExactScopeResult;

  // Appends the lookup scopes corresponding to `base_const_id` to `*scopes`.
  // Returns `false` if not a scope. On invalid scopes, prints a diagnostic, but
  // still updates `*scopes` and returns `true`.
  auto AppendLookupScopesForConstant(SemIR::LocId loc_id,
                                     SemIR::ConstantId base_const_id,
                                     llvm::SmallVector<LookupScope>* scopes)
      -> bool;

  // Performs a qualified name lookup in a specified scopes and in scopes that
  // they extend, returning the referenced instruction.
  auto LookupQualifiedName(SemIR::LocId loc_id, SemIR::NameId name_id,
                           llvm::ArrayRef<LookupScope> lookup_scopes,
                           bool required = true,
                           std::optional<AccessInfo> access_info = std::nullopt)

Review comment (suggestion):
Maybe add comments to the members? Note this is sort of an alternative to the documentation on LookupNameInExactScope (which I note doesn't explain `access_kind`, but that's a pre-existing issue).

```suggestion
  struct LookupNameInExactScopeResult {
    // The matching entity if found, or invalid if poisoned or not found.
    SemIR::InstId inst_id;
    // The access level required to use inst_id, if it's valid.
    SemIR::AccessKind access_kind;
    // Whether a poisoned entry was found.
    bool is_poisoned = false;
```

Or if you'd rather keep documentation on the function, maybe just add a note of where to look:

```suggestion
  // See LookupNameInExactScope for return information.
  struct LookupNameInExactScopeResult {
    SemIR::InstId inst_id;
    SemIR::AccessKind access_kind;
    bool is_poisoned = false;
```

Code after:
      -> void;

  // Replaces the instruction `inst_id` with `inst`, not affecting location.
  // The instruction is required to not change its constant value.
  auto ReplaceInstPreservingConstantValue(SemIR::InstId inst_id,
                                          SemIR::Inst inst) -> void;

  // Sets only the parse node of an instruction. This is only used when setting
  // the parse node of an imported namespace. Versus
  // ReplaceInstBeforeConstantUse, it is safe to use after the namespace is used
  // in constant evaluation. It's exposed this way mainly so that `insts()` can
  // remain const.
  auto SetNamespaceNodeId(SemIR::InstId inst_id, Parse::NodeId node_id)
      -> void {
    sem_ir().insts().SetLocId(inst_id, SemIR::LocId(node_id));
  }

  // Adds a name to name lookup. Prints a diagnostic for name conflicts.
  auto AddNameToLookup(SemIR::NameId name_id, SemIR::InstId target_id) -> void;

  // Performs name lookup in a specified scope for a name appearing in a
  // declaration. If scope_id is invalid, uses the current contextual scope. If
  // found, returns the referenced instruction and false. If poisoned, returns
  // an invalid instruction and true.
  // TODO: For poisoned names, return the poisoning instruction.
  auto LookupNameInDecl(SemIR::LocId loc_id, SemIR::NameId name_id,
                        SemIR::NameScopeId scope_id)
      -> std::pair<SemIR::InstId, bool>;

  // Performs an unqualified name lookup, returning the referenced instruction.
  auto LookupUnqualifiedName(Parse::NodeId node_id, SemIR::NameId name_id,
                             bool required = true) -> LookupResult;

  // Performs a name lookup in a specified scope, returning the referenced
  // instruction. Does not look into extended scopes. Returns an invalid
  // instruction if the name is poisoned or not found.
  // TODO: Return the poisoning instruction if poisoned.
  auto LookupNameInExactScope(SemIRLoc loc, SemIR::NameId name_id,
                              SemIR::NameScopeId scope_id,
                              const SemIR::NameScope& scope)
      -> LookupNameInExactScopeResult;

  // Appends the lookup scopes corresponding to `base_const_id` to `*scopes`.
  // Returns `false` if not a scope. On invalid scopes, prints a diagnostic, but
  // still updates `*scopes` and returns `true`.
  auto AppendLookupScopesForConstant(SemIR::LocId loc_id,
                                     SemIR::ConstantId base_const_id,
                                     llvm::SmallVector<LookupScope>* scopes)
      -> bool;

  // Performs a qualified name lookup in a specified scopes and in scopes that