Merge pull request #96 , originally known as ipld/cidlink-only-usable…

…-as-ptr

In fact this became a docs change; it is often desirable to *not* use the cidlink.Link type as a pointer.

linking.go

@@ -30,6 +30,10 @@ import (
 // It's even possible to use IPLD *entirely without* any linking implementation,
 // using it purely for json/cbor via the encoding packages and
 // foregoing the advanced traversal features around transparent link loading.
+//
+// Link interfaces are usually inhabited by a struct or string or etc, and not a pointer.
+// This is because Link is often desirable to be able to use as a golang map key,
+// and in that context, pointers would not result in the desired behavior.
 type Link interface {
 	// Load consumes serial data from a Loader and funnels the parsed
 	// data into a NodeAssembler.

linking/cid/cidLink.go

@@ -15,6 +15,13 @@ var (
 	_ ipld.LinkBuilder = LinkBuilder{}
 )
 
+// Link implements the ipld.Link interface using a CID.
+// See https://github.com/ipfs/go-cid for more information about CIDs.
+//
+// When using this value, typically you'll use it as `Link`, and not `*Link`.
+// This includes when handling the value as an `ipld.Link` interface -- the non-pointer form is typically preferable.
+// This is because the ipld.Link inteface is often desirable to be able to use as a golang map key,
+// and in that context, pointers would not result in the desired behavior.
 type Link struct {
 	cid.Cid
 }