proto.Equal: document map equality and clarify the rule for repeated fields.

PiperOrigin-RevId: 130971987

proto/equal.go

@@ -54,13 +54,17 @@ Equality is defined in this way:
     in a proto3 .proto file, fields are not "set"; specifically,
     zero length proto3 "bytes" fields are equal (nil == {}).
   - Two repeated fields are equal iff their lengths are the same,
-    and their corresponding elements are equal (a "bytes" field,
-    although represented by []byte, is not a repeated field)
+    and their corresponding elements are equal. Note a "bytes" field,
+    although represented by []byte, is not a repeated field and the
+    rule for the scalar fields described above applies.
   - Two unset fields are equal.
   - Two unknown field sets are equal if their current
     encoded state is equal.
   - Two extension sets are equal iff they have corresponding
     elements that are pairwise equal.
+  - Two map fields are equal iff their lengths are the same,
+    and they contain the same set of elements. Zero-length map
+    fields are equal.
   - Every other combination of things are not equal.
 
 The return value is undefined if a and b are not protocol buffers.

proto/equal_test.go

@@ -183,6 +183,18 @@ var EqualTests = []struct {
 		&pb.MessageWithMap{NameMapping: map[int32]string{1: "Rob"}},
 		false,
 	},
+	{
+		"zero-length maps same",
+		&pb.MessageWithMap{NameMapping: map[int32]string{}},
+		&pb.MessageWithMap{NameMapping: nil},
+		true,
+	},
+	{
+		"orders in map don't matter",
+		&pb.MessageWithMap{NameMapping: map[int32]string{1: "Ken", 2: "Rob"}},
+		&pb.MessageWithMap{NameMapping: map[int32]string{2: "Rob", 1: "Ken"}},
+		true,
+	},
 	{
 		"oneof same",
 		&pb.Communique{Union: &pb.Communique_Number{41}},