add doc comments for all new, recently added API elements (#544)

jhump · Jan 13, 2023 · d2a36df · d2a36df
1 parent 384ff0e
commit d2a36df
Show file tree

Hide file tree

Showing 4 changed files with 55 additions and 3 deletions.
diff --git a/desc/cache.go b/desc/cache.go
@@ -49,9 +49,9 @@ func (c mapCache) put(key protoreflect.Descriptor, val Descriptor) {
 
 type noopCache struct{}
 
-func (noopCache) get(d protoreflect.Descriptor) Descriptor {
+func (noopCache) get(protoreflect.Descriptor) Descriptor {
 	return nil
 }
 
-func (noopCache) put(key protoreflect.Descriptor, val Descriptor) {
+func (noopCache) put(protoreflect.Descriptor, Descriptor) {
 }
diff --git a/desc/descriptor.go b/desc/descriptor.go
@@ -64,10 +64,14 @@ type FileDescriptor struct {
 	sourceInfoRecomputeFunc
 }
 
+// Unwrap returns the underlying protoreflect.Descriptor. Most usages will be more
+// interested in UnwrapFile, which has a more specific return type. This generic
+// version is present to satisfy the DescriptorWrapper interface.
 func (fd *FileDescriptor) Unwrap() protoreflect.Descriptor {
 	return fd.wrapped
 }
 
+// UnwrapFile returns the underlying protoreflect.FileDescriptor.
 func (fd *FileDescriptor) UnwrapFile() protoreflect.FileDescriptor {
 	return fd.wrapped
 }
@@ -284,10 +288,14 @@ type MessageDescriptor struct {
 	jsonNames      jsonNameMap
 }
 
+// Unwrap returns the underlying protoreflect.Descriptor. Most usages will be more
+// interested in UnwrapMessage, which has a more specific return type. This generic
+// version is present to satisfy the DescriptorWrapper interface.
 func (md *MessageDescriptor) Unwrap() protoreflect.Descriptor {
 	return md.wrapped
 }
 
+// UnwrapMessage returns the underlying protoreflect.MessageDescriptor.
 func (md *MessageDescriptor) UnwrapMessage() protoreflect.MessageDescriptor {
 	return md.wrapped
 }
@@ -555,10 +563,14 @@ type FieldDescriptor struct {
 	def            memoizedDefault
 }
 
+// Unwrap returns the underlying protoreflect.Descriptor. Most usages will be more
+// interested in UnwrapField, which has a more specific return type. This generic
+// version is present to satisfy the DescriptorWrapper interface.
 func (fd *FieldDescriptor) Unwrap() protoreflect.Descriptor {
 	return fd.wrapped
 }
 
+// UnwrapField returns the underlying protoreflect.FieldDescriptor.
 func (fd *FieldDescriptor) UnwrapField() protoreflect.FieldDescriptor {
 	return fd.wrapped
 }
@@ -1153,10 +1165,14 @@ type EnumDescriptor struct {
 	sourceInfoPath []int32
 }
 
+// Unwrap returns the underlying protoreflect.Descriptor. Most usages will be more
+// interested in UnwrapEnum, which has a more specific return type. This generic
+// version is present to satisfy the DescriptorWrapper interface.
 func (ed *EnumDescriptor) Unwrap() protoreflect.Descriptor {
 	return ed.wrapped
 }
 
+// UnwrapEnum returns the underlying protoreflect.EnumDescriptor.
 func (ed *EnumDescriptor) UnwrapEnum() protoreflect.EnumDescriptor {
 	return ed.wrapped
 }
@@ -1306,10 +1322,14 @@ type EnumValueDescriptor struct {
 	sourceInfoPath []int32
 }
 
+// Unwrap returns the underlying protoreflect.Descriptor. Most usages will be more
+// interested in UnwrapEnumValue, which has a more specific return type. This generic
+// version is present to satisfy the DescriptorWrapper interface.
 func (vd *EnumValueDescriptor) Unwrap() protoreflect.Descriptor {
 	return vd.wrapped
 }
 
+// UnwrapEnumValue returns the underlying protoreflect.EnumValueDescriptor.
 func (vd *EnumValueDescriptor) UnwrapEnumValue() protoreflect.EnumValueDescriptor {
 	return vd.wrapped
 }
@@ -1415,10 +1435,14 @@ type ServiceDescriptor struct {
 	sourceInfoPath []int32
 }
 
+// Unwrap returns the underlying protoreflect.Descriptor. Most usages will be more
+// interested in UnwrapService, which has a more specific return type. This generic
+// version is present to satisfy the DescriptorWrapper interface.
 func (sd *ServiceDescriptor) Unwrap() protoreflect.Descriptor {
 	return sd.wrapped
 }
 
+// UnwrapService returns the underlying protoreflect.ServiceDescriptor.
 func (sd *ServiceDescriptor) UnwrapService() protoreflect.ServiceDescriptor {
 	return sd.wrapped
 }
@@ -1538,10 +1562,14 @@ type MethodDescriptor struct {
 	sourceInfoPath []int32
 }
 
+// Unwrap returns the underlying protoreflect.Descriptor. Most usages will be more
+// interested in UnwrapMethod, which has a more specific return type. This generic
+// version is present to satisfy the DescriptorWrapper interface.
 func (md *MethodDescriptor) Unwrap() protoreflect.Descriptor {
 	return md.wrapped
 }
 
+// UnwrapMethod returns the underlying protoreflect.MethodDescriptor.
 func (md *MethodDescriptor) UnwrapMethod() protoreflect.MethodDescriptor {
 	return md.wrapped
 }
@@ -1676,10 +1704,14 @@ type OneOfDescriptor struct {
 	sourceInfoPath []int32
 }
 
+// Unwrap returns the underlying protoreflect.Descriptor. Most usages will be more
+// interested in UnwrapOneOf, which has a more specific return type. This generic
+// version is present to satisfy the DescriptorWrapper interface.
 func (od *OneOfDescriptor) Unwrap() protoreflect.Descriptor {
 	return od.wrapped
 }
 
+// UnwrapOneOf returns the underlying protoreflect.OneofDescriptor.
 func (od *OneOfDescriptor) UnwrapOneOf() protoreflect.OneofDescriptor {
 	return od.wrapped
 }

diff --git a/desc/sourceinfo/cmd/protoc-gen-gosrcinfo/main.go b/desc/sourceinfo/cmd/protoc-gen-gosrcinfo/main.go
@@ -10,9 +10,9 @@ import (
 	"path"
 	"strings"
 
-	"github.com/golang/protobuf/proto"
 	"github.com/jhump/gopoet"
 	"github.com/jhump/goprotoc/plugins"
+	"google.golang.org/protobuf/proto"
 	"google.golang.org/protobuf/types/pluginpb"
 
 	"github.com/jhump/protoreflect/desc"

diff --git a/desc/wrap.go b/desc/wrap.go
@@ -18,6 +18,8 @@ type DescriptorWrapper interface {
 	Unwrap() protoreflect.Descriptor
 }
 
+// WrapDescriptor wraps the given descriptor, returning a desc.Descriptor
+// value that represents the same element.
 func WrapDescriptor(d protoreflect.Descriptor) (Descriptor, error) {
 	return wrapDescriptor(d, noopCache{})
 }
@@ -45,6 +47,8 @@ func wrapDescriptor(d protoreflect.Descriptor, cache descriptorCache) (Descripto
 	}
 }
 
+// WrapFiles wraps the given file descriptors, returning a slice of *desc.FileDescriptor
+// values that represent the same files.
 func WrapFiles(d []protoreflect.FileDescriptor) ([]*FileDescriptor, error) {
 	cache := mapCache{}
 	results := make([]*FileDescriptor, len(d))
@@ -58,6 +62,8 @@ func WrapFiles(d []protoreflect.FileDescriptor) ([]*FileDescriptor, error) {
 	return results, nil
 }
 
+// WrapFile wraps the given file descriptor, returning a *desc.FileDescriptor
+// value that represents the same file.
 func WrapFile(d protoreflect.FileDescriptor) (*FileDescriptor, error) {
 	return wrapFile(d, noopCache{})
 }
@@ -67,6 +73,8 @@ func wrapFile(d protoreflect.FileDescriptor, cache descriptorCache) (*FileDescri
 	return convertFile(d, fdp, cache)
 }
 
+// WrapMessage wraps the given message descriptor, returning a *desc.MessageDescriptor
+// value that represents the same message.
 func WrapMessage(d protoreflect.MessageDescriptor) (*MessageDescriptor, error) {
 	return wrapMessage(d, noopCache{})
 }
@@ -86,6 +94,8 @@ func wrapMessage(d protoreflect.MessageDescriptor, cache descriptorCache) (*Mess
 	}
 }
 
+// WrapField wraps the given field descriptor, returning a *desc.FieldDescriptor
+// value that represents the same field.
 func WrapField(d protoreflect.FieldDescriptor) (*FieldDescriptor, error) {
 	return wrapField(d, noopCache{})
 }
@@ -108,6 +118,8 @@ func wrapField(d protoreflect.FieldDescriptor, cache descriptorCache) (*FieldDes
 	}
 }
 
+// WrapOneOf wraps the given oneof descriptor, returning a *desc.OneOfDescriptor
+// value that represents the same oneof.
 func WrapOneOf(d protoreflect.OneofDescriptor) (*OneOfDescriptor, error) {
 	return wrapOneOf(d, noopCache{})
 }
@@ -123,6 +135,8 @@ func wrapOneOf(d protoreflect.OneofDescriptor, cache descriptorCache) (*OneOfDes
 	return nil, fmt.Errorf("oneof has unexpected parent type: %T", parent)
 }
 
+// WrapEnum wraps the given enum descriptor, returning a *desc.EnumDescriptor
+// value that represents the same enum.
 func WrapEnum(d protoreflect.EnumDescriptor) (*EnumDescriptor, error) {
 	return wrapEnum(d, noopCache{})
 }
@@ -142,6 +156,8 @@ func wrapEnum(d protoreflect.EnumDescriptor, cache descriptorCache) (*EnumDescri
 	}
 }
 
+// WrapEnumValue wraps the given enum value descriptor, returning a *desc.EnumValueDescriptor
+// value that represents the same enum value.
 func WrapEnumValue(d protoreflect.EnumValueDescriptor) (*EnumValueDescriptor, error) {
 	return wrapEnumValue(d, noopCache{})
 }
@@ -157,6 +173,8 @@ func wrapEnumValue(d protoreflect.EnumValueDescriptor, cache descriptorCache) (*
 	return nil, fmt.Errorf("enum value has unexpected parent type: %T", parent)
 }
 
+// WrapService wraps the given service descriptor, returning a *desc.ServiceDescriptor
+// value that represents the same service.
 func WrapService(d protoreflect.ServiceDescriptor) (*ServiceDescriptor, error) {
 	return wrapService(d, noopCache{})
 }
@@ -172,6 +190,8 @@ func wrapService(d protoreflect.ServiceDescriptor, cache descriptorCache) (*Serv
 	return nil, fmt.Errorf("service has unexpected parent type: %T", parent)
 }
 
+// WrapMethod wraps the given method descriptor, returning a *desc.MethodDescriptor
+// value that represents the same method.
 func WrapMethod(d protoreflect.MethodDescriptor) (*MethodDescriptor, error) {
 	return wrapMethod(d, noopCache{})
 }