From 746a971656bbea9efb386bb4902ad94f218437f7 Mon Sep 17 00:00:00 2001
From: Dan Gohman <gohman@apple.com>
Date: Fri, 26 Mar 2010 19:39:05 +0000
Subject: [PATCH] Tell "the rest of the story" about LLVM's iterators' implicit
 conversions.

llvm-svn: 99642
---
 docs/ProgrammersManual.html | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html
index a2d32d4e985..d1865f13a79 100644
--- a/docs/ProgrammersManual.html
+++ b/docs/ProgrammersManual.html
@@ -1843,6 +1843,21 @@ void printNextInstruction(Instruction* inst) {
 </pre>
 </div>
 
+<p>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, it
+prevents the following code, where <tt>B</tt> is a <tt>BasicBlock</tt>,
+from compiling:</p>
+
+<div class="doc_code">
+<pre>
+  llvm::SmallVector&lt;llvm::Instruction *, 16&gt;(B-&gt;begin(), B-&gt;end());
+</pre>
+</div>
+
+<p>Because of this, these implicit conversions may be removed some day,
+and <tt>operator*</tt> changed to return a pointer instead of a reference.
+
 </div>
 
 <!--_______________________________________________________________________-->