[llvm] a2691e3 - [docs] remove some out-of-date content in LLVM Programmer's Manual (#74989)

[via llvm-commits]

Author: Yuhao Gu
Date: 2023-12-14T16:31:26+08:00
New Revision: a2691e363232c011fdaace9fcc094f3cd210f78b

URL: https://github.com/llvm/llvm-project/commit/a2691e363232c011fdaace9fcc094f3cd210f78b
DIFF: https://github.com/llvm/llvm-project/commit/a2691e363232c011fdaace9fcc094f3cd210f78b.diff

LOG: [docs] remove some out-of-date content in LLVM Programmer's Manual (#74989)

Remove the part about implicit conversion from an iterator to a pointer.

This part of the manual was written 14 years ago, in:
https://github.com/llvm/llvm-project/commit/37027c30ec526afe3bb571df6f8701bf0d322f22

There do exist a type casting operator in `ilist` then:
https://github.com/llvm/llvm-project/blob/37027c30ec526afe3bb571df6f8701bf0d322f22/llvm/include/llvm/ADT/ilist.h#L192-L194

But it has been remove since 2016:
https://github.com/llvm/llvm-project/commit/f197b1f78f854d8513ef617b8cfc61860f7b4b84

So I think it makes sense to remove this part to avoid mislead new
contributors.

Added: 
    

Modified: 
    llvm/docs/ProgrammersManual.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst
index 551a23c0570e96..491e6b1dd2498b 100644
--- a/llvm/docs/ProgrammersManual.rst
+++ b/llvm/docs/ProgrammersManual.rst
@@ -2747,24 +2747,6 @@ pointer from an iterator is very straight-forward.  Assuming that ``i`` is a
   Instruction* pinst = &*i; // Grab pointer to instruction reference
   const Instruction& inst = *j;
 
-However, the iterators you'll be working with in the LLVM framework are special:
-they will automatically convert to a ptr-to-instance type whenever they need to.
-Instead of dereferencing the iterator and then taking the address of the result,
-you can simply assign the iterator to the proper pointer type and you get the
-dereference and address-of operation as a result of the assignment (behind the
-scenes, this is a result of overloading casting mechanisms).  Thus the second
-line of the last example,
-
-.. code-block:: c++
-
-  Instruction *pinst = &*i;
-
-is semantically equivalent to
-
-.. code-block:: c++
-
-  Instruction *pinst = i;
-
 It's also possible to turn a class pointer into the corresponding iterator, and
 this is a constant time operation (very efficient).  The following code snippet
 illustrates use of the conversion constructors provided by LLVM iterators.  By
@@ -2779,18 +2761,6 @@ obtaining it via iteration over some structure:
     if (it != inst->getParent()->end()) errs() << *it << "\n";
   }
 
-Unfortunately, these implicit conversions come at a cost; they prevent these
-iterators from conforming to standard iterator conventions, and thus from being
-usable with standard algorithms and containers.  For example, they prevent the
-following code, where ``B`` is a ``BasicBlock``, from compiling:
-
-.. code-block:: c++
-
-  llvm::SmallVector<llvm::Instruction *, 16>(B->begin(), B->end());
-
-Because of this, these implicit conversions may be removed some day, and
-``operator*`` changed to return a pointer instead of a reference.
-
 .. _iterate_complex:
 
 Finding call sites: a slightly more complex example