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

[Yuhao Gu via llvm-commits]

https://github.com/yhgu2000 created https://github.com/llvm/llvm-project/pull/119565

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.

>From 065fcae2215e7d75c9285cb9dae53100f0b24963 Mon Sep 17 00:00:00 2001
From: Yuhao Gu <yhgu2000 at outlook.com>
Date: Sun, 10 Dec 2023 19:47:50 +0800
Subject: [PATCH] [docs] remove some out-of-date content in LLVM Programmer's
 Manual.

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.
---
 llvm/docs/ProgrammersManual.rst | 30 ------------------------------
 1 file changed, 30 deletions(-)

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