diff --git a/README.md b/README.md
index b63ffa2..7ff9854 100644
--- a/README.md
+++ b/README.md
@@ -7,18 +7,20 @@
 ### Simple
 
 ```go
-import "github.com/jbenet/go-multiaddr"
+import ma "github.com/jbenet/go-multiaddr"
 
-m := multiaddr.NewMultiaddr("/ip4/127.0.0.1/udp/1234")
-// <Multiaddr /ip4/127.0.0.1/udp/1234>
-m.buffer
-// <Buffer >
-m.String()
-// /ip4/127.0.0.1/udp/1234
+// construct from a string (err signals parse failure)
+m1, err := ma.NewMultiaddr("/ip4/127.0.0.1/udp/1234")
 
-// construct with Buffer
-m = multiaddr.Multiaddr{ Bytes: m.Bytes }
-// <Multiaddr /ip4/127.0.0.1/udp/1234>
+// construct from bytes (err signals parse failure)
+m2, err := ma.NewMultiaddrBytes(m1.Bytes())
+
+// true
+strings.Equal(m1.String(), "/ip4/127.0.0.1/udp/1234")
+strings.Equal(m1.String(), m2.String())
+bytes.Equal(m1.Bytes(), m2.Bytes())
+m1.Equal(m2)
+m2.Equal(m1)
 ```
 
 ### Protocols
@@ -36,7 +38,7 @@ addr.Protocols()
 
 ```go
 // handles the stupid url version too
-m = multiaddr.NewUrl("udp4://127.0.0.1:1234")
+m = ma.NewUrl("udp4://127.0.0.1:1234")
 // <Multiaddr /ip4/127.0.0.1/udp/1234>
 m.Url(buf)
 // udp4://127.0.0.1:1234
@@ -45,9 +47,9 @@ m.Url(buf)
 ### En/decapsulate
 
 ```go
-m.Encapsulate(m.NewMultiaddr("/sctp/5678"))
+m.Encapsulate(ma.NewMultiaddr("/sctp/5678"))
 // <Multiaddr /ip4/127.0.0.1/udp/1234/sctp/5678>
-m.Decapsulate(m.NewMultiaddr("/udp")) // up to + inc last occurrence of subaddr
+m.Decapsulate(ma.NewMultiaddr("/udp")) // up to + inc last occurrence of subaddr
 // <Multiaddr /ip4/127.0.0.1>
 ```
 
@@ -56,11 +58,11 @@ m.Decapsulate(m.NewMultiaddr("/udp")) // up to + inc last occurrence of subaddr
 Multiaddr allows expressing tunnels very nicely.
 
 ```js
-printer := multiaddr.NewMultiaddr("/ip4/192.168.0.13/tcp/80")
-proxy := multiaddr.NewMultiaddr("/ip4/10.20.30.40/tcp/443")
+printer, _ := ma.NewMultiaddr("/ip4/192.168.0.13/tcp/80")
+proxy, _ := ma.NewMultiaddr("/ip4/10.20.30.40/tcp/443")
 printerOverProxy := proxy.Encapsulate(printer)
-// <Multiaddr /ip4/10.20.30.40/tcp/443/ip4/192.168.0.13/tcp/80>
+// /ip4/10.20.30.40/tcp/443/ip4/192.168.0.13/tcp/80
 
-proxyAgain := printerOverProxy.Decapsulate(multiaddr.NewMultiaddr("/ip4"))
-// <Multiaddr /ip4/10.20.30.40/tcp/443>
+proxyAgain := printerOverProxy.Decapsulate(printer)
+// /ip4/10.20.30.40/tcp/443
 ```
diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..c26e443
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,36 @@
+/*
+Package multiaddr provides an implementation of the Multiaddr network
+address format. Multiaddr emphasizes explicitness, self-description, and
+portability. It allows applications to treat addresses as opaque tokens,
+and to avoid making assumptions about the address representation (e.g. length).
+Learn more at https://github.com/jbenet/multiaddr
+
+Basic Use:
+
+  import (
+    "bytes"
+    "strings"
+    ma "github.com/jbenet/go-multiaddr"
+  )
+
+  // construct from a string (err signals parse failure)
+  m1, err := ma.NewMultiaddr("/ip4/127.0.0.1/udp/1234")
+
+  // construct from bytes (err signals parse failure)
+  m2, err := ma.NewMultiaddrBytes(m1.Bytes())
+
+  // true
+  strings.Equal(m1.String(), "/ip4/127.0.0.1/udp/1234")
+  strings.Equal(m1.String(), m2.String())
+  bytes.Equal(m1.Bytes(), m2.Bytes())
+  m1.Equal(m2)
+  m2.Equal(m1)
+
+  // tunneling (en/decap)
+  printer, _ := ma.NewMultiaddr("/ip4/192.168.0.13/tcp/80")
+  proxy, _ := ma.NewMultiaddr("/ip4/10.20.30.40/tcp/443")
+  printerOverProxy := proxy.Encapsulate(printer)
+  proxyAgain := printerOverProxy.Decapsulate(printer)
+
+*/
+package multiaddr