[docs] Updates ProgrammersManual to reflect the change that BasicBlock::getInstList() is private.

[dbabokin]

llvm/docs/ProgrammersManual.rst

2990

New version of ReplaceInstWithValue accepts only two argument, so looks like the whole instToReplace->getParent() needs to be removed.

[vporpo]

llvm/docs/ProgrammersManual.rst

2990

Good catch, let me try to fix this.

llvm/docs/ProgrammersManual.rst

 where ``indexLoc`` is now the logical name of the instruction's execution value,
 which is a pointer to an integer on the run time stack.
 
 *Inserting instructions*
 
 There are essentially three ways to insert an ``Instruction`` into an existing
 sequence of instructions that form a ``BasicBlock``:
 
-* Insertion into an explicit instruction list
+* Insertion into the instruction list of the ``BasicBlock``
 
   Given a ``BasicBlock* pb``, an ``Instruction* pi`` within that ``BasicBlock``,
   and a newly-created instruction we wish to insert before ``*pi``, we do the
   following:
 
   .. code-block:: c++
 
       BasicBlock *pb = ...;
       Instruction *pi = ...;
       auto *newInst = new Instruction(...);
 
-      pb->getInstList().insert(pi, newInst); // Inserts newInst before pi in pb
+      newInst->insertBefore(pi); // Inserts newInst before pi
 
   Appending to the end of a ``BasicBlock`` is so common that the ``Instruction``
   class and ``Instruction``-derived classes provide constructors which take a
   pointer to a ``BasicBlock`` to be appended to.  For example code that looked
   like:
 
   .. code-block:: c++
 
     BasicBlock *pb = ...;
     auto *newInst = new Instruction(...);
 
-    pb->getInstList().push_back(newInst); // Appends newInst to pb
+    newInst->insertAt(pb, pb->end()); // Appends newInst to pb
 
   becomes:
 
   .. code-block:: c++
 
     BasicBlock *pb = ...;
     auto *newInst = new Instruction(..., pb);
 
   which is much cleaner, especially if you are creating long instruction
   streams.
 
-* Insertion into an implicit instruction list
-
-  ``Instruction`` instances that are already in ``BasicBlock``\ s are implicitly
-  associated with an existing instruction list: the instruction list of the
-  enclosing basic block.  Thus, we could have accomplished the same thing as the
-  above code without being given a ``BasicBlock`` by doing:
-
-  .. code-block:: c++
-
-    Instruction *pi = ...;
-    auto *newInst = new Instruction(...);
-
-    pi->getParent()->getInstList().insert(pi, newInst);
-
-  In fact, this sequence of steps occurs so frequently that the ``Instruction``
-  class and ``Instruction``-derived classes provide constructors which take (as
-  a default parameter) a pointer to an ``Instruction`` which the newly-created
-  ``Instruction`` should precede.  That is, ``Instruction`` constructors are
-  capable of inserting the newly-created instance into the ``BasicBlock`` of a
-  provided instruction, immediately before that instruction.  Using an
-  ``Instruction`` constructor with a ``insertBefore`` (default) parameter, the
-  above code becomes:
-
-  .. code-block:: c++
-
-    Instruction* pi = ...;
-    auto *newInst = new Instruction(..., pi);
-
-  which is much cleaner, especially if you're creating a lot of instructions and
-  adding them to ``BasicBlock``\ s.
-
 * Insertion using an instance of ``IRBuilder``
 
   Inserting several ``Instruction``\ s can be quite laborious using the previous
   methods. The ``IRBuilder`` is a convenience class that can be used to add
   several instructions to the end of a ``BasicBlock`` or before a particular
   ``Instruction``. It also supports constant folding and renaming named
   registers (see ``IRBuilder``'s template arguments).
 
* ``ReplaceInstWithValue``
   replacement of the result of a particular ``AllocaInst`` that allocates memory
   for a single integer with a null pointer to an integer.
 
   .. code-block:: c++
 
     AllocaInst* instToReplace = ...;
     BasicBlock::iterator ii(instToReplace);
 
-    ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
+    ReplaceInstWithValue(instToReplace->getParent(), ii,
                          Constant::getNullValue(PointerType::getUnqual(Type::Int32Ty)));
 
 * ``ReplaceInstWithInst``
 
   This function replaces a particular instruction with another instruction,
   inserting the new instruction into the basic block at the location where the
   old instruction was, and replacing any uses of the old instruction with the
   new instruction.  The following example illustrates the replacement of one
   ``AllocaInst`` with another.
 
   .. code-block:: c++
 
     AllocaInst* instToReplace = ...;
     BasicBlock::iterator ii(instToReplace);
 
-    ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
+    ReplaceInstWithInst(instToReplace->getParent(), ii,
                         new AllocaInst(Type::Int32Ty, 0, "ptrToReplacedInt"));
 
 
 Replacing multiple uses of Users and Values
 """""""""""""""""""""""""""""""""""""""""""
 
 You can use ``Value::replaceAllUsesWith`` and ``User::replaceUsesOfWith`` to
 change more than one use at a time.  See the doxygen documentation for the
* ``BasicBlock(const std::string &Name = "", Function *Parent = 0)``
   ``Parent`` parameter is specified, the new ``BasicBlock`` is automatically
   inserted at the end of the specified :ref:`Function <c_Function>`, if not
   specified, the BasicBlock must be manually inserted into the :ref:`Function
   <c_Function>`.
 
 * | ``BasicBlock::iterator`` - Typedef for instruction list iterator
   | ``BasicBlock::const_iterator`` - Typedef for const_iterator.
   | ``begin()``, ``end()``, ``front()``, ``back()``,
-    ``size()``, ``empty()``
+    ``size()``, ``empty()``, ``splice()``
     STL-style functions for accessing the instruction list.
 
   These methods and typedefs are forwarding functions that have the same
   semantics as the standard library methods of the same names.  These methods
   expose the underlying instruction list of a basic block in a way that is easy
-  to manipulate.  To get the full complement of container operations (including
-  operations to update the list), you must use the ``getInstList()`` method.
-
-* ``BasicBlock::InstListType &getInstList()``
-
-  This method is used to get access to the underlying container that actually
-  holds the Instructions.  This method must be used when there isn't a
-  forwarding function in the ``BasicBlock`` class for the operation that you
-  would like to perform.  Because there are no forwarding functions for
-  "updating" operations, you need to use this if you want to update the contents
-  of a ``BasicBlock``.
+  to manipulate.
 
 * ``Function *getParent()``
 
   Returns a pointer to :ref:`Function <c_Function>` the block is embedded into,
   or a null pointer if it is homeless.
 
 * ``Instruction *getTerminator()``