proto: minor doc changes

Change-Id: I9e74b6b68a0bfe96381f224df7c56e49795d17d6
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/219501
Reviewed-by: Damien Neil <dneil@google.com>

proto/doc.go

@@ -22,30 +22,29 @@
 // This package contains functions to convert to and from the wire format,
 // an efficient binary serialization of protocol buffers.
 //
+// • Size reports the size of a message in the wire format.
+//
 // • Marshal converts a message to the wire format.
 // The MarshalOptions type provides more control over wire marshaling.
 //
 // • Unmarshal converts a message from the wire format.
 // The UnmarshalOptions type provides more control over wire unmarshaling.
 //
-// • Size reports the size of a message in the wire format.
-//
 //
 // Basic message operations
 //
 // • Clone makes a deep copy of a message.
 //
+// • Merge merges the content of a message into another.
+//
 // • Equal compares two messages. For more control over comparisons
 // and detailed reporting of differences, see package
 // "google.golang.org/protobuf/testing/protocmp".
 //
+// • Reset clears the content of a message.
+//
 // • IsInitialized reports whether all required fields in a message are set.
 //
-// • Merge combines two messages. The MergeOptions type provides more
-// control over merge operations.
-//
-// • Reset clears the contents of a message.
-//
 //
 // Optional scalar constructors
 //
@@ -53,22 +52,22 @@
 // as pointers to a value. For example, an optional string field has the
 // Go type *string.
 //
-// • Bool, Float32, Float64, Int32, Int64, String, Uint32, and Uint64
-// take a value and return a pointer to a new instance of it, to
-// simplify construction of optional field values.
+// • Bool, Int32, Int64, Uint32, Uint64, Float32, Float64, and String
+// take a value and return a pointer to a new instance of it,
+// to simplify construction of optional field values.
 //
 // Generated enum types usually have an Enum method which performs the
 // same operation.
 //
-// Optional values are only supported in proto2.
+// Optional scalar fields are only supported in proto2.
 //
 //
 // Extension accessors
 //
-// • GetExtension, SetExtension, ClearExtension, and HasExtension access
-// extension field values in generated messages.
+// • HasExtension, GetExtension, SetExtension, and ClearExtension
+// access extension field values in a protocol buffer message.
 //
-// Extensions are only supported in proto2.
+// Extension fields are only supported in proto2.
 //
 //
 // Related packages

proto/encode.go

@@ -62,8 +62,8 @@ type MarshalOptions struct {
 	// 2. The message and all its submessages have not changed in any
 	// way since the Size call.
 	//
-	// If either of these invariants is broken, the results are undefined
-	// but may include panics or invalid output.
+	// If either of these invariants is violated,
+	// the results are undefined and may include panics or corrupted output.
 	//
 	// Implementations MAY take this option into account to provide
 	// better performance, but there is no guarantee that they will do so.

proto/extension.go

@@ -9,25 +9,28 @@ import (
 )
 
 // HasExtension reports whether an extension field is populated.
+// It panics if ext does not extend m.
 func HasExtension(m Message, ext protoreflect.ExtensionType) bool {
 	return m.ProtoReflect().Has(ext.TypeDescriptor())
 }
 
 // ClearExtension clears an extension field such that subsequent
 // HasExtension calls return false.
+// It panics if ext does not extend m.
 func ClearExtension(m Message, ext protoreflect.ExtensionType) {
 	m.ProtoReflect().Clear(ext.TypeDescriptor())
 }
 
 // GetExtension retrieves the value for an extension field.
-//
 // If the field is unpopulated, it returns the default value for
 // scalars and an immutable, empty value for lists, maps, or messages.
+// It panics if ext does not extend m.
 func GetExtension(m Message, ext protoreflect.ExtensionType) interface{} {
 	return ext.InterfaceOf(m.ProtoReflect().Get(ext.TypeDescriptor()))
 }
 
 // SetExtension stores the value of an extension field.
+// It panics if ext does not extend m or if value type is invalid for the field.
 func SetExtension(m Message, ext protoreflect.ExtensionType, value interface{}) {
 	m.ProtoReflect().Set(ext.TypeDescriptor(), ext.ValueOf(value))
 }

proto/merge.go

@@ -8,7 +8,7 @@ import (
 	"google.golang.org/protobuf/reflect/protoreflect"
 )
 
-// Merge merges src into dst, which must be messages with the same descriptor.
+// Merge merges src into dst, which must be a message with the same descriptor.
 //
 // Populated scalar fields in src are copied to dst, while populated
 // singular messages in src are merged into dst by recursively calling Merge.
@@ -27,7 +27,7 @@ func Merge(dst, src Message) {
 	mergeOptions{}.mergeMessage(dstMsg, srcMsg)
 }
 
-// Clone returns a copy of m.
+// Clone returns a deep copy of m.
 // If the top-level message is invalid, it returns an invalid message as well.
 func Clone(m Message) Message {
 	// NOTE: Most usages of Clone assume the following properties: