Repository: carbon-language/carbon-lang
File: toolchain/sem_ir/formatter.h (C/C++)

Code before:

  // Determines whether a single instruction should be included in the
  // formatted output.
  auto ShouldFormatInst(InstId inst_id) -> bool;

  // Begins a braced block. Writes an open brace, and prepares to insert a
  // newline after it if the braced block is non-empty.
  auto OpenBrace() -> void;

  // Ends a braced block by writing a close brace.
  auto CloseBrace() -> void;

  auto Semicolon() -> void;

  // Adds beginning-of-line indentation. If we're at the start of a braced
  // block, first starts a new line.
  auto Indent(int offset = 0) -> void;

  // Adds beginning-of-label indentation. This is one level less than normal
  // indentation. Labels also get a preceding blank line unless they're at the
  // start of a block.
  auto IndentLabel() -> void;

  // Formats a top-level scope, and any of the instructions in that scope that
  // are used. Instructions may optionally use `TentativeOutputScope` (see type
  // for details).
  auto FormatTopLevelScopeIfUsed(InstNamer::ScopeId scope_id,
                                 llvm::ArrayRef<InstId> block,
                                 bool is_tentative) -> void;

  // Formats a full class.
  auto FormatClass(ClassId id) -> void;

  // Formats a full interface.
  auto FormatInterface(InterfaceId id) -> void;

  // Formats an associated constant entity.
  auto FormatAssociatedConstant(AssociatedConstantId id) -> void;

  // Formats a full impl.
  auto FormatImpl(ImplId id) -> void;

  // Formats a full function.
  auto FormatFunction(FunctionId id) -> void;

  // Helper for FormatSpecific to print regions.
  auto FormatSpecificRegion(const Generic& generic, const Specific& specific,
                            GenericInstIndex::Region region,
                            llvm::StringRef region_name) -> void;

  // Formats a full specific.

Review comment (security):
This phrasing makes it unclear whether this is giving permission to the caller or the callee, and how it relates to `is_tentative`.

```suggestion
  // are used. If `is_tentative` is true, the instructions will be formatted using 
  // `TentativeOutputScope` (see type for details).
```

I think it would be better to document this without relying so heavily on implementation details like `TentativeOutputScope`, but I don't understand `TentativeOutputScope` well enough to suggest how to phrase that.

Code after:

  // Adds a new chunk to the output. Does not flush existing output, so should
  // only be called if there is no buffered output.
  auto AddChunkNoFlush(bool include_in_output) -> size_t;

  // Flushes the current chunk and add a new chunk to the output.
  auto AddChunk(bool include_in_output) -> size_t;

  // Marks the given chunk as being included in the output if the current chunk
  // is.
  auto IncludeChunkInOutput(size_t chunk) -> void;

  // Returns true if the instruction should be included according to its
  // originating IR. Typically `ShouldFormatEntity` should be used instead.
  auto ShouldIncludeInstByIR(InstId inst_id) -> bool;

  // Determines whether the specified entity should be included in the formatted
  // output. `is_definition_start` should indicate whether, if `decl_id`'s
  // `LocId` is a `NodeId`, it is expected to be a `DefinitionStart` kind.
  auto ShouldFormatEntity(InstId decl_id, bool is_definition_start) -> bool;

  auto ShouldFormatEntity(const EntityWithParamsBase& entity) -> bool;

  // Determines whether a single instruction should be included in the
  // formatted output.
  auto ShouldFormatInst(InstId inst_id) -> bool;

  // Begins a braced block. Writes an open brace, and prepares to insert a
  // newline after it if the braced block is non-empty.
  auto OpenBrace() -> void;

  // Ends a braced block by writing a close brace.
  auto CloseBrace() -> void;

  auto Semicolon() -> void;

  // Adds beginning-of-line indentation. If we're at the start of a braced
  // block, first starts a new line.
  auto Indent(int offset = 0) -> void;

  // Adds beginning-of-label indentation. This is one level less than normal
  // indentation. Labels also get a preceding blank line unless they're at the
  // start of a block.
  auto IndentLabel() -> void;

  // Formats a top-level scope, and any of the instructions in that scope that
  // are used.
  auto FormatTopLevelScopeIfUsed(InstNamer::ScopeId scope_id,
                                 llvm::ArrayRef<InstId> block,
                                 bool use_tentative_output_scopes) -> void;