Add and update comments in ui/build/upload.go

Bug: b/172918852
Test: go test .
Change-Id: I63ca307e3935fc5a91a550889601397300ba395e

ui/build/upload.go

@@ -30,32 +30,34 @@ import (
 )
 
 const (
+	// Used to generate a raw protobuf file that contains information
+	// of the list of metrics files from host to destination storage.
 	uploadPbFilename = ".uploader.pb"
 )
 
 var (
-	// For testing purpose
+	// For testing purpose.
-	getTmpDir = ioutil.TempDir
+	tmpDir = ioutil.TempDir
 )
 
 // UploadMetrics uploads a set of metrics files to a server for analysis. An
-// uploader full path is required to be specified in order to upload the set
+// uploader full path is specified in ANDROID_ENABLE_METRICS_UPLOAD environment
-// of metrics files. This is accomplished by defining the ANDROID_ENABLE_METRICS_UPLOAD
+// variable in order to upload the set of metrics files. The metrics files are
-// environment variable. The metrics files are copied to a temporary directory
+// first copied to a temporary directory and the uploader is then executed in
-// and the uploader is then executed in the background to allow the user to continue
+// the background to allow the user/system to continue working. Soong communicates
-// working.
+// to the uploader through the upload_proto raw protobuf file.
 func UploadMetrics(ctx Context, config Config, simpleOutput bool, buildStarted time.Time, files ...string) {
 	ctx.BeginTrace(metrics.RunSetupTool, "upload_metrics")
 	defer ctx.EndTrace()
 
 	uploader := config.MetricsUploaderApp()
-	// No metrics to upload if the path to the uploader was not specified.
 	if uploader == "" {
+		// If the uploader path was not specified, no metrics shall be uploaded.
 		return
 	}
 
-	// Some files may not exist. For example, build errors protobuf file
+	// Some files passed in to this function may not exist. For example,
-	// may not exist since the build was successful.
+	// build errors protobuf file may not exist since the build was successful.
 	var metricsFiles []string
 	for _, f := range files {
 		if _, err := os.Stat(f); err == nil {
@@ -70,7 +72,7 @@ func UploadMetrics(ctx Context, config Config, simpleOutput bool, buildStarted t
 	// The temporary directory cannot be deleted as the metrics uploader is started
 	// in the background and requires to exist until the operation is done. The
 	// uploader can delete the directory as it is specified in the upload proto.
-	tmpDir, err := getTmpDir("", "upload_metrics")
+	tmpDir, err := tmpDir("", "upload_metrics")
 	if err != nil {
 		ctx.Fatalf("failed to create a temporary directory to store the list of metrics files: %v\n", err)
 	}
@@ -103,7 +105,7 @@ func UploadMetrics(ctx Context, config Config, simpleOutput bool, buildStarted t
 	}
 
 	// Start the uploader in the background as it takes several milliseconds to start the uploader
-	// and prepare the metrics for upload. This affects small commands like "lunch".
+	// and prepare the metrics for upload. This affects small shell commands like "lunch".
 	cmd := Command(ctx, config, "upload metrics", uploader, "--upload-metrics", pbFile)
 	if simpleOutput {
 		cmd.RunOrFatal()

ui/build/upload_test.go

@@ -62,16 +62,16 @@ func TestUploadMetrics(t *testing.T) {
 			}
 			defer os.RemoveAll(outDir)
 
-			// Supply our own getTmpDir to delete the temp dir once the test is done.
+			// Supply our own tmpDir to delete the temp dir once the test is done.
-			orgGetTmpDir := getTmpDir
+			orgTmpDir := tmpDir
-			getTmpDir = func(string, string) (string, error) {
+			tmpDir = func(string, string) (string, error) {
 				retDir := filepath.Join(outDir, "tmp_upload_dir")
 				if err := os.Mkdir(retDir, 0755); err != nil {
 					t.Fatalf("failed to create temporary directory %q: %v", retDir, err)
 				}
 				return retDir, nil
 			}
-			defer func() { getTmpDir = orgGetTmpDir }()
+			defer func() { tmpDir = orgTmpDir }()
 
 			metricsUploadDir := filepath.Join(outDir, ".metrics_uploader")
 			if err := os.Mkdir(metricsUploadDir, 0755); err != nil {
@@ -134,11 +134,11 @@ func TestUploadMetricsErrors(t *testing.T) {
 			}
 			defer os.RemoveAll(outDir)
 
-			orgGetTmpDir := getTmpDir
+			orgTmpDir := tmpDir
-			getTmpDir = func(string, string) (string, error) {
+			tmpDir = func(string, string) (string, error) {
 				return tt.tmpDir, tt.tmpDirErr
 			}
-			defer func() { getTmpDir = orgGetTmpDir }()
+			defer func() { tmpDir = orgTmpDir }()
 
 			metricsFile := filepath.Join(outDir, "metrics_file_1")
 			if err := ioutil.WriteFile(metricsFile, []byte("test file"), 0644); err != nil {