Improve docs for protosourcepath package

private/buf/buftarget/controlling_workspace.go

@@ -25,7 +25,7 @@ type ControllingWorkspace interface {
  // buf.work.yaml or v2 buf.yaml workspace configuration is located.
  Path() string
  // Returns a buf.work.yaml file that was found for the controlling workspace.
- // This is empty if we are retruning a buf.yaml.
+ // This is empty if we are returning a buf.yaml.
  BufWorkYAMLFile() bufconfig.BufWorkYAMLFile
  // Returns a buf.yaml that was found for the controlling workspace.
  // This is empty if we are returning a buf.work.yaml.

private/bufpkg/bufprotoplugin/bufprotoplugin.go

@@ -108,7 +108,7 @@ type PluginResponse struct {
  PluginOut string
 }
 
-// NewPluginResponse retruns a new *PluginResponse.
+// NewPluginResponse returns a new *PluginResponse.
 func NewPluginResponse(
  response *pluginpb.CodeGeneratorResponse,
  pluginName string,

private/pkg/protosourcepath/enum.go

@@ -27,46 +27,56 @@ const (
  enumReservedNameTypeTag = int32(5)
 )
 
+// enums is the state when an element representing enums in the source path was parsed.
 func enums(
  _ int32,
- sourcePath protoreflect.SourcePath,
- i int,
+ fullSourcePath protoreflect.SourcePath,
+ index int,
  excludeChildAssociatedPaths bool,
 ) (state, []protoreflect.SourcePath, error) {
  associatedPaths := []protoreflect.SourcePath{
- currentPath(sourcePath, i),
+ currentPath(fullSourcePath, index),
  }
  if !excludeChildAssociatedPaths {
  associatedPaths = append(
  associatedPaths,
- childAssociatedPath(sourcePath, i, enumNameTypeTag),
+ childAssociatedPath(fullSourcePath, index, enumNameTypeTag),
  )
  }
- if len(sourcePath) == i+1 {
+ if len(fullSourcePath) == index+1 {
  // This path does not extend beyond the enum declaration, return associated paths and
  // terminate here.
  return nil, associatedPaths, nil
  }
  return enum, associatedPaths, nil
 }
 
-func enum(token int32, sourcePath protoreflect.SourcePath, i int, _ bool) (state, []protoreflect.SourcePath, error) {
+// enum is the state when an element representing a specific child path of an enum was parsed.
+func enum(token int32, fullSourcePath protoreflect.SourcePath, index int, _ bool) (state, []protoreflect.SourcePath, error) {
  switch token {
  case enumNameTypeTag:
  // The enum name has already been added, can terminate here immediately.
  return nil, nil, nil
  case enumValuesTypeTag:
- if len(sourcePath) < i+2 {
- return nil, nil, newInvalidSourcePathError(sourcePath, "cannot have enum value declaration without index")
+ // We check to make sure that the length of the source path contains at least the current
+ // token and an index. This is because all source paths for enum values are expected
+ // to have indices.
+ if len(fullSourcePath) < index+2 {
+ return nil, nil, newInvalidSourcePathError(fullSourcePath, "cannot have enum value declaration without index")
  }
  return enumValues, nil, nil
  case enumOptionTypeTag:
- // Return the entire path and then handle the option
- return options, []protoreflect.SourcePath{slicesext.Copy(sourcePath)}, nil
+ // For options, we add the full path and then return the options state to validate
+ // the path.
+ return options, []protoreflect.SourcePath{slicesext.Copy(fullSourcePath)}, nil
  case enumReservedRangeTypeTag:
- return reservedRanges, []protoreflect.SourcePath{currentPath(sourcePath, i)}, nil
+ // For reserved ranges, we add the full path and then return the reserved ranges state to
+ // validate the path.
+ return reservedRanges, []protoreflect.SourcePath{currentPath(fullSourcePath, index)}, nil
  case enumReservedNameTypeTag:
- return reservedNames, []protoreflect.SourcePath{currentPath(sourcePath, i)}, nil
+ // For reserved names, we add the full path and then return the reserved names state to
+ // validate the path.
+ return reservedNames, []protoreflect.SourcePath{currentPath(fullSourcePath, index)}, nil
  }
- return nil, nil, newInvalidSourcePathError(sourcePath, "invalid enum path")
+ return nil, nil, newInvalidSourcePathError(fullSourcePath, "invalid enum path")
 }

private/pkg/protosourcepath/enumvalue.go

@@ -32,30 +32,34 @@ var (
  }
 )
 
+// enumValues is the state when an element representing enum values in the source path was
+// parsed.
 func enumValues(
  _ int32,
- sourcePath protoreflect.SourcePath,
- i int,
+ fullSourcePath protoreflect.SourcePath,
+ index int,
  excludeChildAssociatedPaths bool,
 ) (state, []protoreflect.SourcePath, error) {
  associatedPaths := []protoreflect.SourcePath{
- currentPath(sourcePath, i),
+ currentPath(fullSourcePath, index),
  }
  if !excludeChildAssociatedPaths {
  associatedPaths = append(
  associatedPaths,
- childAssociatedPath(sourcePath, i, enumValueNameTypeTag),
- childAssociatedPath(sourcePath, i, enumValueNumberTypeTag),
+ childAssociatedPath(fullSourcePath, index, enumValueNameTypeTag),
+ childAssociatedPath(fullSourcePath, index, enumValueNumberTypeTag),
  )
  }
- if len(sourcePath) == i+1 {
+ if len(fullSourcePath) == index+1 {
  // This does not extend beyond the enum value declaration, return associated paths and
  // terminate here.
  return nil, associatedPaths, nil
  }
  return enumValue, associatedPaths, nil
 }
 
+// enumValue is the state when an element representing a specific child path of an enum was
+// parsed.
 func enumValue(token int32, sourcePath protoreflect.SourcePath, i int, _ bool) (state, []protoreflect.SourcePath, error) {
  // TODO: use slices.Contains in the future
  if slicesext.ElementsContained(
@@ -67,7 +71,8 @@ func enumValue(token int32, sourcePath protoreflect.SourcePath, i int, _ bool) (
  }
  switch token {
  case enumValueOptionTypeTag:
- // Return the entire path and then handle the option
+ // For options, we add the full path and then return the options state to validate
+ // the path.
  return options, []protoreflect.SourcePath{slicesext.Copy(sourcePath)}, nil
  }
  return nil, nil, newInvalidSourcePathError(sourcePath, "invalid enum value path")

private/pkg/protosourcepath/field.go

@@ -41,34 +41,36 @@ var (
  }
 )
 
+// fields is the state when an element representing fields in the source path was parsed.
 func fields(
  _ int32,
- sourcePath protoreflect.SourcePath,
- i int,
+ fullSourcePath protoreflect.SourcePath,
+ index int,
  excludeChildAssociatedPaths bool,
 ) (state, []protoreflect.SourcePath, error) {
  associatedPaths := []protoreflect.SourcePath{
- currentPath(sourcePath, i),
+ currentPath(fullSourcePath, index),
  }
  if !excludeChildAssociatedPaths {
  associatedPaths = append(
  associatedPaths,
- childAssociatedPath(sourcePath, i, fieldNameTypeTag),
- childAssociatedPath(sourcePath, i, fieldNumberTypeTag),
- childAssociatedPath(sourcePath, i, fieldLabelTypeTag),
- childAssociatedPath(sourcePath, i, fieldTypeTypeTag),
- childAssociatedPath(sourcePath, i, fieldTypeNameTypeTag),
+ childAssociatedPath(fullSourcePath, index, fieldNameTypeTag),
+ childAssociatedPath(fullSourcePath, index, fieldNumberTypeTag),
+ childAssociatedPath(fullSourcePath, index, fieldLabelTypeTag),
+ childAssociatedPath(fullSourcePath, index, fieldTypeTypeTag),
+ childAssociatedPath(fullSourcePath, index, fieldTypeNameTypeTag),
  )
  }
- if len(sourcePath) == i+1 {
+ if len(fullSourcePath) == index+1 {
  // This does not extend beyond the field declaration, return the associated paths and
  // terminate here.
  return nil, associatedPaths, nil
  }
  return field, associatedPaths, nil
 }
 
-func field(token int32, sourcePath protoreflect.SourcePath, i int, _ bool) (state, []protoreflect.SourcePath, error) {
+// field is the state when an element representing a specific child path of a field was parsed.
+func field(token int32, fullSourcePath protoreflect.SourcePath, index int, _ bool) (state, []protoreflect.SourcePath, error) {
  // TODO: use slices.Contains in the future
  if slicesext.ElementsContained(
  terminalFieldTokens,
@@ -79,29 +81,34 @@ func field(token int32, sourcePath protoreflect.SourcePath, i int, _ bool) (stat
  }
  switch token {
  case fieldOptionTypeTag:
- // Return the entire path and then handle the option
- return options, []protoreflect.SourcePath{slicesext.Copy(sourcePath)}, nil
+ // For options, we add the full path and then return the options state to validate
+ // the path.
+ return options, []protoreflect.SourcePath{slicesext.Copy(fullSourcePath)}, nil
  case fieldDefaultValueTypeTag:
- return nil, []protoreflect.SourcePath{currentPath(sourcePath, i)}, nil
+ // Default value is a terminal path, but was not already added to our associated paths,
+ // since default values are specific to proto2. Add the path and terminate.
+ return nil, []protoreflect.SourcePath{currentPath(fullSourcePath, index)}, nil
  }
- return nil, nil, newInvalidSourcePathError(sourcePath, "invalid field path")
+ return nil, nil, newInvalidSourcePathError(fullSourcePath, "invalid field path")
 }
 
+// extensions is the state when an element representing extensions in the source path was parsed.
 func extensions(
  token int32,
- sourcePath protoreflect.SourcePath,
- i int,
+ fullSourcePath protoreflect.SourcePath,
+ index int,
  excludeChildAssociatedPaths bool,
 ) (state, []protoreflect.SourcePath, error) {
- // An extension is effectively a field descriptor, so we start by getting all paths for fields.
- field, associatedPaths, err := fields(token, sourcePath, i, excludeChildAssociatedPaths)
+ // Extensions share the same descriptor proto definition as fields, so we can parse them
+ // using the same states.
+ field, associatedPaths, err := fields(token, fullSourcePath, index, excludeChildAssociatedPaths)
  if err != nil {
  return nil, nil, err
  }
  if !excludeChildAssociatedPaths {
  associatedPaths = append(
  associatedPaths,
- childAssociatedPath(sourcePath, i, extensionExtendeeTypeTag),
+ childAssociatedPath(fullSourcePath, index, extensionExtendeeTypeTag),
  )
  }
  return field, associatedPaths, nil