Comment the eliminateDeadInstruction and related APIs.

When the underlying utility was changed for OSSA, it changed the
semantics of the callback, which breaks the way I've always used a
deletion callback to update iterators.

/// \p callback is called on each deleted instruction before deleting any
/// instructions. This way, the SIL is valid in the callback. However, the
/// callback cannot be used to update instruction iterators since other
/// instructions to be deleted remain in the instruction list.

Author: atrick

include/swift/SILOptimizer/Utils/InstOptUtils.h

@@ -85,6 +85,11 @@ class InstructionDeleter {
 
   /// If the instruction \p inst is dead, delete it immediately and record
   /// its operands so that they can be cleaned up later.
+  ///
+  /// \p callback is called on each deleted instruction before deleting any
+  /// instructions. This way, the SIL is valid in the callback. However, the
+  /// callback cannot be used to update instruction iterators since other
+  /// instructions to be deleted remain in the instruction list.
   void deleteIfDead(
       SILInstruction *inst,
       llvm::function_ref<void(SILInstruction *)> callback =
@@ -102,8 +107,10 @@ class InstructionDeleter {
   /// \pre the instruction to be deleted must not have any use other than
   /// incidental uses.
   ///
-  /// \param callback a callback called whenever an instruction
-  /// is deleted.
+  /// \p callback is called on each deleted instruction before deleting any
+  /// instructions. This way, the SIL is valid in the callback. However, the
+  /// callback cannot be used to update instruction iterators since other
+  /// instructions to be deleted remain in the instruction list.
   void forceDeleteAndFixLifetimes(
       SILInstruction *inst,
       llvm::function_ref<void(SILInstruction *)> callback =
@@ -122,8 +129,10 @@ class InstructionDeleter {
   /// \pre the instruction to be deleted must not have any use other than
   /// incidental uses.
   ///
-  /// \param callback a callback called whenever an instruction
-  /// is deleted.
+  /// \p callback is called on each deleted instruction before deleting any
+  /// instructions. This way, the SIL is valid in the callback. However, the
+  /// callback cannot be used to update instruction iterators since other
+  /// instructions to be deleted remain in the instruction list.
   void forceDelete(
       SILInstruction *inst,
       llvm::function_ref<void(SILInstruction *)> callback =
@@ -137,7 +146,10 @@ class InstructionDeleter {
   /// function body in an inconsistent state, it needs to be made consistent
   /// before this method is invoked.
   ///
-  /// \param callback a callback called whenever an instruction is deleted.
+  /// \p callback is called on each deleted instruction before deleting any
+  /// instructions. This way, the SIL is valid in the callback. However, the
+  /// callback cannot be used to update instruction iterators since other
+  /// instructions to be deleted remain in the instruction list.
   void
   cleanUpDeadInstructions(llvm::function_ref<void(SILInstruction *)> callback =
                               [](SILInstruction *) {});
@@ -170,7 +182,10 @@ class InstructionDeleter {
 /// \pre the SIL function containing the instruction is assumed to be
 /// consistent, i.e., does not have under or over releases.
 ///
-/// \param callback a callback called whenever an instruction is deleted.
+/// \p callback is called on each deleted instruction before deleting any
+/// instructions. This way, the SIL is valid in the callback. However, the
+/// callback cannot be used to update instruction iterators since other
+/// instructions to be deleted remain in the instruction list.
 void eliminateDeadInstruction(
     SILInstruction *inst, llvm::function_ref<void(SILInstruction *)> callback =
                               [](SILInstruction *) {});