Tell "the rest of the story" about LLVM's iterators' implicit conversions.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@99642 91177308-0d34-0410-b5e6-96231b3b80d8

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>
 
 <!--_______________________________________________________________________-->