encoding/{protojson,prototext}: strengthen wording on stability

Because these encoders use internal/detrand to make their output
nondeterministic across builds, use stronger wording to warn users of
their instability.

Updates golang/protobuf#1121

Change-Id: Ia809e5c26ce24d17f602e7fbae26d9df2b57d05b
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/579895
LUCI-TryBot-Result: Go LUCI <[email protected]>
Auto-Submit: Lasse Folger <[email protected]>
Reviewed-by: Lasse Folger <[email protected]>
Reviewed-by: Michael Stapelberg <[email protected]>

Author: adg

encoding/protojson/encode.go

@@ -25,15 +25,17 @@ const defaultIndent = "  "
 
 // Format formats the message as a multiline string.
 // This function is only intended for human consumption and ignores errors.
-// Do not depend on the output being stable. It may change over time across
-// different versions of the program.
+// Do not depend on the output being stable. Its output will change across
+// different builds of your program, even when using the same version of the
+// protobuf module.
 func Format(m proto.Message) string {
 	return MarshalOptions{Multiline: true}.Format(m)
 }
 
 // Marshal writes the given [proto.Message] in JSON format using default options.
-// Do not depend on the output being stable. It may change over time across
-// different versions of the program.
+// Do not depend on the output being stable. Its output will change across
+// different builds of your program, even when using the same version of the
+// protobuf module.
 func Marshal(m proto.Message) ([]byte, error) {
 	return MarshalOptions{}.Marshal(m)
 }
@@ -110,8 +112,9 @@ type MarshalOptions struct {
 
 // Format formats the message as a string.
 // This method is only intended for human consumption and ignores errors.
-// Do not depend on the output being stable. It may change over time across
-// different versions of the program.
+// Do not depend on the output being stable. Its output will change across
+// different builds of your program, even when using the same version of the
+// protobuf module.
 func (o MarshalOptions) Format(m proto.Message) string {
 	if m == nil || !m.ProtoReflect().IsValid() {
 		return "<nil>" // invalid syntax, but okay since this is for debugging
@@ -122,8 +125,9 @@ func (o MarshalOptions) Format(m proto.Message) string {
 }
 
 // Marshal marshals the given [proto.Message] in the JSON format using options in
-// MarshalOptions. Do not depend on the output being stable. It may change over
-// time across different versions of the program.
+// Do not depend on the output being stable. Its output will change across
+// different builds of your program, even when using the same version of the
+// protobuf module.
 func (o MarshalOptions) Marshal(m proto.Message) ([]byte, error) {
 	return o.marshal(nil, m)
 }

encoding/prototext/encode.go

@@ -27,15 +27,17 @@ const defaultIndent = "  "
 
 // Format formats the message as a multiline string.
 // This function is only intended for human consumption and ignores errors.
-// Do not depend on the output being stable. It may change over time across
-// different versions of the program.
+// Do not depend on the output being stable. Its output will change across
+// different builds of your program, even when using the same version of the
+// protobuf module.
 func Format(m proto.Message) string {
 	return MarshalOptions{Multiline: true}.Format(m)
 }
 
 // Marshal writes the given [proto.Message] in textproto format using default
-// options. Do not depend on the output being stable. It may change over time
-// across different versions of the program.
+// options. Do not depend on the output being stable. Its output will change
+// across different builds of your program, even when using the same version of
+// the protobuf module.
 func Marshal(m proto.Message) ([]byte, error) {
 	return MarshalOptions{}.Marshal(m)
 }
@@ -84,8 +86,9 @@ type MarshalOptions struct {
 
 // Format formats the message as a string.
 // This method is only intended for human consumption and ignores errors.
-// Do not depend on the output being stable. It may change over time across
-// different versions of the program.
+// Do not depend on the output being stable. Its output will change across
+// different builds of your program, even when using the same version of the
+// protobuf module.
 func (o MarshalOptions) Format(m proto.Message) string {
 	if m == nil || !m.ProtoReflect().IsValid() {
 		return "<nil>" // invalid syntax, but okay since this is for debugging
@@ -98,8 +101,9 @@ func (o MarshalOptions) Format(m proto.Message) string {
 }
 
 // Marshal writes the given [proto.Message] in textproto format using options in
-// MarshalOptions object. Do not depend on the output being stable. It may
-// change over time across different versions of the program.
+// MarshalOptions object. Do not depend on the output being stable. Its output
+// will change across different builds of your program, even when using the
+// same version of the protobuf module.
 func (o MarshalOptions) Marshal(m proto.Message) ([]byte, error) {
 	return o.marshal(nil, m)
 }