doc/effective_go: clarify advice on returning interfaces

New Gophers sometimes misconstrue the advice in the "Generality" section
as "export interfaces instead of implementations" and add needless
interfaces to their code as a result.  Down the road, they end up
needing to add methods and either break existing callers or have to
resort to unpleasant hacks (e.g. using "magic method" type-switches).

Weaken the first paragraph of this section to only advise leaving types
unexported when they will never need additional methods.

Change-Id: I32a1ae44012b5896faf167c02e192398a4dfc0b8
Reviewed-on: https://go-review.googlesource.com/24892
Reviewed-by: Rob Pike <[email protected]>
Reviewed-by: Andrew Gerrand <[email protected]>

Author: Bryan C. Mills

doc/effective_go.html

@@ -2238,13 +2238,12 @@ <h3 id="interface_conversions">Interface conversions and type assertions</h3>
 
 <h3 id="generality">Generality</h3>
 <p>
-If a type exists only to implement an interface
-and has no exported methods beyond that interface,
-there is no need to export the type itself.
-Exporting just the interface makes it clear that
-it's the behavior that matters, not the implementation,
-and that other implementations with different properties
-can mirror the behavior of the original type.
+If a type exists only to implement an interface and will
+never have exported methods beyond that interface, there is
+no need to export the type itself.
+Exporting just the interface makes it clear the value has no
+interesting behavior beyond what is described in the
+interface.
 It also avoids the need to repeat the documentation
 on every instance of a common method.
 </p>
@@ -3665,4 +3664,3 @@ <h2 id="web_server">A web server</h2>
 var _ image.Image = Black
 </pre>
 -->
-