From 09cd13c51dabd709e79329a9b8591fc4d15b6f3f Mon Sep 17 00:00:00 2001
From: Rob Pike <r@golang.org>
Date: Fri, 15 Mar 2013 11:38:50 -0700
Subject: [PATCH] doc/go_faq.html: add entry about pointer to interface

R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/7546050
---
 doc/go_faq.html | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/doc/go_faq.html b/doc/go_faq.html
index 4c5ead8c59..fab1702a21 100644
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -974,6 +974,57 @@ struct.  If the interface value holds a pointer, copying the interface value
 makes a copy of the pointer, but again not the data it points to.
 </p>
 
+<h3 id="pointer_to_interface">
+When should I use a pointer to an interface?</h3>
+
+<p>
+Almost never. Pointers to interface values arise only in rare, tricky situations involving
+disguising an interface value's type for delayed evaluation.
+</p>
+
+<p>
+It is however a common mistake to pass a pointer to an interface value
+to a function expecting an interface. The compiler will complain about this
+error but the situation can still be confusing, because sometimes a
+<a href="#different_method_sets">pointer
+is necessary to satisfy an interface</a>.
+The insight is that although a pointer to a concrete type can satisfy
+an interface, with one exception <em>a pointer to an interface can never satisfy a interface</em>.
+</p>
+
+<p>
+Consider the variable declaration,
+</p>
+
+<pre>
+var w io.Writer
+</pre>
+
+<p>
+The printing function <code>fmt.Fprintf</code> takes as its first argument
+a value that satisfies <code>io.Writer</code>—something that implements
+the canonical <code>Write</code> method. Thus we can write
+</p>
+
+<pre>
+fmt.Fprintf(w, "hello, world\n")
+</pre>
+
+<p>
+If however we pass the address of <code>w</code>, the program will not compile.
+</p>
+
+<pre>
+fmt.Fprintf(&amp;w, "hello, world\n") // Compile-time error.
+</pre>
+
+<p>
+The one exception is that any value, even a pointer to an interface, can be assigned to
+a variable of empty interface type (<code>interface{}</code>).
+Even so, it's almost certainly a mistake if the value is a pointer to an interface;
+the result can be confusing.
+</p>
+
 <h3 id="methods_on_values_or_pointers">
 Should I define methods on values or pointers?</h3>
 
-- 
2.48.1