all: document that Unmarshal must be a mutable message
Fixes #937
Change-Id: I40b2678eba0195ed01676167f8e01e2fedea293b
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/302329
Trust: Joe Tsai <joetsai@digital-static.net>
Reviewed-by: Damien Neil <dneil@google.com>
diff --git a/encoding/protojson/decode.go b/encoding/protojson/decode.go
index e6953ad..07da5db 100644
--- a/encoding/protojson/decode.go
+++ b/encoding/protojson/decode.go
@@ -24,6 +24,7 @@
)
// Unmarshal reads the given []byte into the given proto.Message.
+// The provided message must be mutable (e.g., a non-nil pointer to a message).
func Unmarshal(b []byte, m proto.Message) error {
return UnmarshalOptions{}.Unmarshal(b, m)
}
@@ -48,10 +49,11 @@
}
}
-// Unmarshal reads the given []byte and populates the given proto.Message using
-// options in UnmarshalOptions object. It will clear the message first before
-// setting the fields. If it returns an error, the given message may be
-// partially set.
+// Unmarshal reads the given []byte and populates the given proto.Message
+// using options in the UnmarshalOptions object.
+// It will clear the message first before setting the fields.
+// If it returns an error, the given message may be partially set.
+// The provided message must be mutable (e.g., a non-nil pointer to a message).
func (o UnmarshalOptions) Unmarshal(b []byte, m proto.Message) error {
return o.unmarshal(b, m)
}
diff --git a/encoding/prototext/decode.go b/encoding/prototext/decode.go
index e2bbf7c..8fb1d9e 100644
--- a/encoding/prototext/decode.go
+++ b/encoding/prototext/decode.go
@@ -22,6 +22,7 @@
)
// Unmarshal reads the given []byte into the given proto.Message.
+// The provided message must be mutable (e.g., a non-nil pointer to a message).
func Unmarshal(b []byte, m proto.Message) error {
return UnmarshalOptions{}.Unmarshal(b, m)
}
@@ -50,8 +51,9 @@
}
}
-// Unmarshal reads the given []byte and populates the given proto.Message using options in
-// UnmarshalOptions object.
+// Unmarshal reads the given []byte and populates the given proto.Message
+// using options in the UnmarshalOptions object.
+// The provided message must be mutable (e.g., a non-nil pointer to a message).
func (o UnmarshalOptions) Unmarshal(b []byte, m proto.Message) error {
return o.unmarshal(b, m)
}
diff --git a/proto/decode.go b/proto/decode.go
index a0efaa0..49f9b8c 100644
--- a/proto/decode.go
+++ b/proto/decode.go
@@ -45,12 +45,14 @@
}
// Unmarshal parses the wire-format message in b and places the result in m.
+// The provided message must be mutable (e.g., a non-nil pointer to a message).
func Unmarshal(b []byte, m Message) error {
_, err := UnmarshalOptions{}.unmarshal(b, m.ProtoReflect())
return err
}
// Unmarshal parses the wire-format message in b and places the result in m.
+// The provided message must be mutable (e.g., a non-nil pointer to a message).
func (o UnmarshalOptions) Unmarshal(b []byte, m Message) error {
_, err := o.unmarshal(b, m.ProtoReflect())
return err
