diff --git a/interface.go b/interface.go
index 23d0eb7..699c54d 100644
--- a/interface.go
+++ b/interface.go
@@ -50,6 +50,8 @@ type Multiaddr interface {
 	// Decapsulate removes a Multiaddr wrapping. For example:
 	//
 	//      /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 6cba615..62ccc32 100644
--- a/multiaddr_test.go
+++ b/multiaddr_test.go
@@ -434,6 +434,16 @@ func TestDecapsulateComment(t *testing.T) {
 	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) {