proto: minor doc changes
Change-Id: I9e74b6b68a0bfe96381f224df7c56e49795d17d6
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/219501
Reviewed-by: Damien Neil <dneil@google.com>
diff --git a/proto/doc.go b/proto/doc.go
index f001b93..e1d13d7 100644
--- a/proto/doc.go
+++ b/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
diff --git a/proto/encode.go b/proto/encode.go
index 65e951e..3625091 100644
--- a/proto/encode.go
+++ b/proto/encode.go
@@ -62,8 +62,8 @@
// 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.
diff --git a/proto/extension.go b/proto/extension.go
index 809c12d..b89413b 100644
--- a/proto/extension.go
+++ b/proto/extension.go
@@ -9,25 +9,28 @@
)
// 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))
}
diff --git a/proto/merge.go b/proto/merge.go
index b60fd01..aecc8e4 100644
--- a/proto/merge.go
+++ b/proto/merge.go
@@ -8,7 +8,7 @@
"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 @@
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:
