From b08bc6ee84ab8c0d66b033d20e814446278c11e8 Mon Sep 17 00:00:00 2001 From: Joe Tsai Date: Fri, 14 Feb 2020 11:11:07 -0800 Subject: [PATCH] proto: minor doc changes Change-Id: I9e74b6b68a0bfe96381f224df7c56e49795d17d6 Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/219501 Reviewed-by: Damien Neil --- proto/doc.go | 27 +++++++++++++-------------- proto/encode.go | 4 ++-- proto/extension.go | 5 ++++- proto/merge.go | 4 ++-- 4 files changed, 21 insertions(+), 19 deletions(-) diff --git a/proto/doc.go b/proto/doc.go index f001b93f..e1d13d70 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 65e951e7..36250919 100644 --- a/proto/encode.go +++ b/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. diff --git a/proto/extension.go b/proto/extension.go index 809c12de..b89413b6 100644 --- a/proto/extension.go +++ b/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)) } diff --git a/proto/merge.go b/proto/merge.go index b60fd01e..aecc8e42 100644 --- a/proto/merge.go +++ b/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: