all: imp docs

internal/agh/agh.go

@@ -33,6 +33,8 @@ func (em EmptyConfigModifier) Apply(ctx context.Context) {}
 
 // exitErr implements [executil.ExitCodeError] for tests to simulate non-zero
 // process exit codes.
+//
+// TODO(s.chzhen):  Consider constructing an [exec.ExitError] instead.
 type exitErr struct {
 	code osutil.ExitCode
 }

internal/aghos/os.go

@@ -119,9 +119,9 @@ func PIDByCommand(
 	//
 	// TODO(s.chzhen):  Consider streaming the output if needed.  Using
 	// [io.Pipe] here is unnecessary; it complicates lifecycle management
-	// because you must read concurrently and explicitly Close the PipeWriter to
-	// signal EOF.  Since this command’s output is small, a bytes.Buffer via
-	// executil.Run is simplest and safe.
+	// because the output must be read concurrently, and the PipeWriter must be
+	// explicitly closed to signal EOF.  Since this command's output is small, a
+	// bytes.Buffer via executil.Run is sufficient.
 	runErr := executil.Run(
 		ctx,
 		executil.SystemCommandConstructor{},

internal/home/service_linux.go

@@ -171,9 +171,9 @@ func (s *systemdService) Status() (status service.Status, err error) {
 
 	// TODO(s.chzhen):  Consider streaming the output if needed.  Using
 	// [io.Pipe] here is unnecessary; it complicates lifecycle management
-	// because you must read concurrently and explicitly Close the PipeWriter to
-	// signal EOF.  Since this command’s output is small, a bytes.Buffer via
-	// executil.Run is simplest and safe.
+	// because the output must be read concurrently, and the PipeWriter must be
+	// explicitly closed to signal EOF.  Since this command's output is small, a
+	// bytes.Buffer via executil.Run is sufficient.
 	err = executil.Run(
 		// TODO(s.chzhen):  Pass context.
 		context.TODO(),

scripts/translations/main.go

@@ -489,9 +489,9 @@ func changedLocales(
 
 	// TODO(s.chzhen):  Consider streaming the output if needed.  Using
 	// [io.Pipe] here is unnecessary; it complicates lifecycle management
-	// because you must read concurrently and explicitly Close the PipeWriter to
-	// signal EOF.  Since this command’s output is small, a bytes.Buffer via
-	// executil.Run is simplest and safe.
+	// because the output must be read concurrently, and the PipeWriter must be
+	// explicitly closed to signal EOF.  Since this command's output is small, a
+	// bytes.Buffer via executil.Run is sufficient.
 	var out bytes.Buffer
 	err = executil.Run(ctx, cmdCons, &executil.CommandConfig{
 		Path:   gitCmd,