Clarify paths.go somewhat

Bug: 35562758
Test: make

Change-Id: I4cf05ffdd0962186f490467829e3576b4e269c47
diff --git a/android/paths.go b/android/paths.go
index 0d26dc0..a23dd74 100644
--- a/android/paths.go
+++ b/android/paths.go
@@ -97,6 +97,8 @@
 type WritablePath interface {
 	Path
 
+	// the writablePath method doesn't directly do anything,
+	// but it allows a struct to distinguish between whether or not it implements the WritablePath interface
 	writablePath()
 }
 
@@ -137,7 +139,7 @@
 	if path, ok := p.(resPathProvider); ok {
 		return path.resPathWithName(ctx, name)
 	}
-	reportPathError(ctx, "Tried to create object file from unsupported path: %s (%s)", reflect.TypeOf(p).Name(), p)
+	reportPathError(ctx, "Tried to create res file from unsupported path: %s (%s)", reflect.TypeOf(p).Name(), p)
 	return PathForModuleRes(ctx)
 }
 
@@ -188,7 +190,7 @@
 			ret := make(Paths, 0, len(paths))
 			intermediates := filepath.Join(modCtx.ModuleDir(), modCtx.ModuleName(), modCtx.ModuleSubDir(), "missing")
 			for _, path := range paths {
-				p := OptionalPathForSource(ctx, intermediates, path)
+				p := ExistentPathForSource(ctx, intermediates, path)
 				if p.Valid() {
 					ret = append(ret, p.Path())
 				} else {
@@ -205,13 +207,13 @@
 	return ret
 }
 
-// PathsForOptionalSource returns a list of Paths rooted from SrcDir that are
+// ExistentPathsForSources returns a list of Paths rooted from SrcDir that are
 // found in the tree. If any are not found, they are omitted from the list,
 // and dependencies are added so that we're re-run when they are added.
-func PathsForOptionalSource(ctx PathContext, intermediates string, paths []string) Paths {
+func ExistentPathsForSources(ctx PathContext, intermediates string, paths []string) Paths {
 	ret := make(Paths, 0, len(paths))
 	for _, path := range paths {
-		p := OptionalPathForSource(ctx, intermediates, path)
+		p := ExistentPathForSource(ctx, intermediates, path)
 		if p.Valid() {
 			ret = append(ret, p.Path())
 		}
@@ -337,12 +339,11 @@
 	return ret
 }
 
-// PathForSource returns a SourcePath for the provided paths... (which are
-// joined together with filepath.Join). This also validates that the path
-// doesn't escape the source dir, or is contained in the build dir. On error, it
-// will return a usable, but invalid SourcePath, and report a ModuleError.
-func PathForSource(ctx PathContext, paths ...string) SourcePath {
-	p := validatePath(ctx, paths...)
+// PathForSource joins the provided path components and validates that the result
+// neither escapes the source dir nor is in the out dir.
+// On error, it will return a usable, but invalid SourcePath, and report a ModuleError.
+func PathForSource(ctx PathContext, pathComponents ...string) SourcePath {
+	p := validatePath(ctx, pathComponents...)
 	ret := SourcePath{basePath{p, pathConfig(ctx), ""}}
 
 	abs, err := filepath.Abs(ret.String())
@@ -368,16 +369,16 @@
 	return ret
 }
 
-// OptionalPathForSource returns an OptionalPath with the SourcePath if the
+// ExistentPathForSource returns an OptionalPath with the SourcePath if the
 // path exists, or an empty OptionalPath if it doesn't exist. Dependencies are added
 // so that the ninja file will be regenerated if the state of the path changes.
-func OptionalPathForSource(ctx PathContext, intermediates string, paths ...string) OptionalPath {
-	if len(paths) == 0 {
+func ExistentPathForSource(ctx PathContext, intermediates string, pathComponents ...string) OptionalPath {
+	if len(pathComponents) == 0 {
 		// For when someone forgets the 'intermediates' argument
 		panic("Missing path(s)")
 	}
 
-	p := validatePath(ctx, paths...)
+	p := validatePath(ctx, pathComponents...)
 	path := SourcePath{basePath{p, pathConfig(ctx), ""}}
 
 	abs, err := filepath.Abs(path.String())
@@ -483,12 +484,11 @@
 
 var _ Path = OutputPath{}
 
-// PathForOutput returns an OutputPath for the provided paths... (which are
-// joined together with filepath.Join). This also validates that the path
-// does not escape the build dir. On error, it will return a usable, but invalid
-// OutputPath, and report a ModuleError.
-func PathForOutput(ctx PathContext, paths ...string) OutputPath {
-	path := validatePath(ctx, paths...)
+// PathForOutput joins the provided paths and returns an OutputPath that is
+// validated to not escape the build dir.
+// On error, it will return a usable, but invalid OutputPath, and report a ModuleError.
+func PathForOutput(ctx PathContext, pathComponents ...string) OutputPath {
+	path := validatePath(ctx, pathComponents...)
 	return OutputPath{basePath{path, pathConfig(ctx), ""}}
 }
 
@@ -597,7 +597,7 @@
 	}
 	refDumpFileStr := "prebuilts/abi-dumps/" + vndkOrNdkDir + "/" + version + "/" +
 		archName + "/" + sourceOrBinaryDir + "/" + fileName + ext
-	return OptionalPathForSource(ctx, "", refDumpFileStr)
+	return ExistentPathForSource(ctx, "", refDumpFileStr)
 }
 
 // PathForModuleOut returns a Path representing the paths... under the module's
@@ -647,8 +647,8 @@
 
 // PathForModuleObj returns a Path representing the paths... under the module's
 // 'obj' directory.
-func PathForModuleObj(ctx ModuleContext, paths ...string) ModuleObjPath {
-	p := validatePath(ctx, paths...)
+func PathForModuleObj(ctx ModuleContext, pathComponents ...string) ModuleObjPath {
+	p := validatePath(ctx, pathComponents...)
 	return ModuleObjPath{PathForModuleOut(ctx, "obj", p)}
 }
 
@@ -662,14 +662,14 @@
 
 // PathForModuleRes returns a Path representing the paths... under the module's
 // 'res' directory.
-func PathForModuleRes(ctx ModuleContext, paths ...string) ModuleResPath {
-	p := validatePath(ctx, paths...)
+func PathForModuleRes(ctx ModuleContext, pathComponents ...string) ModuleResPath {
+	p := validatePath(ctx, pathComponents...)
 	return ModuleResPath{PathForModuleOut(ctx, "res", p)}
 }
 
 // PathForModuleInstall returns a Path representing the install path for the
 // module appended with paths...
-func PathForModuleInstall(ctx ModuleContext, paths ...string) OutputPath {
+func PathForModuleInstall(ctx ModuleContext, pathComponents ...string) OutputPath {
 	var outPaths []string
 	if ctx.Device() {
 		partition := "system"
@@ -689,14 +689,14 @@
 	if ctx.Debug() {
 		outPaths = append([]string{"debug"}, outPaths...)
 	}
-	outPaths = append(outPaths, paths...)
+	outPaths = append(outPaths, pathComponents...)
 	return PathForOutput(ctx, outPaths...)
 }
 
 // validateSafePath validates a path that we trust (may contain ninja variables).
 // Ensures that each path component does not attempt to leave its component.
-func validateSafePath(ctx PathContext, paths ...string) string {
-	for _, path := range paths {
+func validateSafePath(ctx PathContext, pathComponents ...string) string {
+	for _, path := range pathComponents {
 		path := filepath.Clean(path)
 		if path == ".." || strings.HasPrefix(path, "../") || strings.HasPrefix(path, "/") {
 			reportPathError(ctx, "Path is outside directory: %s", path)
@@ -706,20 +706,20 @@
 	// TODO: filepath.Join isn't necessarily correct with embedded ninja
 	// variables. '..' may remove the entire ninja variable, even if it
 	// will be expanded to multiple nested directories.
-	return filepath.Join(paths...)
+	return filepath.Join(pathComponents...)
 }
 
 // validatePath validates that a path does not include ninja variables, and that
 // each path component does not attempt to leave its component. Returns a joined
 // version of each path component.
-func validatePath(ctx PathContext, paths ...string) string {
-	for _, path := range paths {
+func validatePath(ctx PathContext, pathComponents ...string) string {
+	for _, path := range pathComponents {
 		if strings.Contains(path, "$") {
 			reportPathError(ctx, "Path contains invalid character($): %s", path)
 			return ""
 		}
 	}
-	return validateSafePath(ctx, paths...)
+	return validateSafePath(ctx, pathComponents...)
 }
 
 type testPath struct {