diff --git a/interface.go b/interface.go
index 0c2198b..699c54d 100644
--- a/interface.go
+++ b/interface.go
@@ -47,9 +47,11 @@ type Multiaddr interface {
 	//
 	Encapsulate(Multiaddr) Multiaddr
 
-	// Decapsultate removes a Multiaddr wrapping. For example:
+	// Decapsulate removes a Multiaddr wrapping. For example:
 	//
-	//      /ip4/1.2.3.4/tcp/80 decapsulate /ip4/1.2.3.4 = /tcp/80
+	//      /ip4/1.2.3.4/tcp/80 decapsulate /tcp/80 = /ip4/1.2.3.4
+	//      /ip4/1.2.3.4/tcp/80 decapsulate /udp/80 = /ip4/1.2.3.4/tcp/80
+	//      /ip4/1.2.3.4/tcp/80 decapsulate /ip4/1.2.3.4 = nil
 	//
 	Decapsulate(Multiaddr) Multiaddr
 
diff --git a/multiaddr_test.go b/multiaddr_test.go
index 1eb9d73..62ccc32 100644
--- a/multiaddr_test.go
+++ b/multiaddr_test.go
@@ -427,6 +427,25 @@ func TestEncapsulate(t *testing.T) {
 	}
 }
 
+func TestDecapsulateComment(t *testing.T) {
+	// shows the behavior from the interface comment
+	m := StringCast("/ip4/1.2.3.4/tcp/80")
+	rest := m.Decapsulate(StringCast("/tcp/80"))
+	if rest.String() != "/ip4/1.2.3.4" {
+		t.Fatalf("Documented behavior is not correct. Expected %v saw %v", "/ip4/1.2.3.4/", rest.String())
+	}
+
+	m = StringCast("/ip4/1.2.3.4/tcp/80")
+	rest = m.Decapsulate(StringCast("/udp/80"))
+	if !rest.Equal(m) {
+		t.Fatalf("Documented behavior is not correct. Expected %v saw %v", "/ip4/1.2.3.4/tcp/80", rest.String())
+	}
+
+	m = StringCast("/ip4/1.2.3.4/tcp/80")
+	rest = m.Decapsulate(StringCast("/ip4/1.2.3.4"))
+	require.Nil(t, rest, "expected a nil multiaddr if we decapsulate everything")
+}
+
 func assertValueForProto(t *testing.T, a Multiaddr, p int, exp string) {
 	t.Logf("checking for %s in %s", ProtocolWithCode(p).Name, a)
 	fv, err := a.ValueForProtocol(p)