Add comments

go/private/actions/compilepkg.bzl

@@ -263,6 +263,12 @@ def _run_nogo(
     args.add("-out_log", out_log)
     args.add("-nogo", nogo)
 
+    # This action runs nogo and produces the facts files for downstream nogo actions.
+    # It is important that this action doesn't fail if nogo produces findings, which allows users
+    # to get the nogo findings for all targets with --keep_going rather than stopping at the first
+    # target with findings.
+    # If nogo fails for any other reason, the action still fails, which allows users to debug their
+    # analyzers with --sandbox_debug.
     go.actions.run(
         inputs = inputs,
         outputs = outputs,
@@ -275,6 +281,9 @@ def _run_nogo(
         progress_message = "Running nogo on %{label}",
     )
 
+    # This is a separate action that produces the validation output registered with Bazel. It
+    # prints any nogo findings and, crucially, fails if there are any findings. This is necessary
+    # to actually fail the build on nogo findings, which RunNogo doesn't do.
     validation_args = go.actions.args()
     validation_args.add("nogovalidation")
     validation_args.add(out_validation)

go/tools/builders/compilepkg.go

@@ -260,6 +260,7 @@ func compileArchive(
 	// When coverage is set, source files will be modified during instrumentation. We should only run static analysis
 	// over original source files and not the modified ones.
 	// goSrcsNogo and cgoSrcsNogo are copies of the original source files for nogo to run static analysis.
+	// TODO: Use slices.Clone when 1.21 is the minimal supported version.
 	goSrcsNogo := append([]string{}, goSrcs...)
 	cgoSrcsNogo := append([]string{}, cgoSrcs...)
 
@@ -319,13 +320,17 @@ func compileArchive(
 	var objFiles []string
 	if compilingWithCgo {
 		var srcDir string
-		// Also run cgo on original source files, not coverage instrumented, if
-		// using nogo.
 		if coverMode != "" && cgoGoSrcsForNogoPath != "" {
+			// If the package uses Cgo, compile .s and .S files with cgo2, not the Go assembler.
+			// Otherwise: the .s/.S files will be compiled with the Go assembler later
 			srcDir, goSrcs, objFiles, err = cgo2(goenv, goSrcs, cgoSrcs, cSrcs, cxxSrcs, objcSrcs, objcxxSrcs, sSrcs, hSrcs, packagePath, packageName, cc, cppFlags, cFlags, cxxFlags, objcFlags, objcxxFlags, ldFlags, cgoExportHPath, "")
 			if err != nil {
 				return err
 			}
+			// Also run cgo on original source files, not coverage instrumented, if using nogo.
+			// The compilation outputs are not used, but the generated sources are passed to
+			// the separate nogo action.
+			// TODO: Only run cgo, don't compile.
 			_, _, _, err = cgo2(goenv, goSrcsNogo, cgoSrcsNogo, cSrcs, cxxSrcs, objcSrcs, objcxxSrcs, sSrcs, hSrcs, packagePath, packageName, cc, cppFlags, cFlags, cxxFlags, objcFlags, objcxxFlags, ldFlags, cgoExportHPath, cgoGoSrcsForNogoPath)
 			if err != nil {
 				return err

go/tools/builders/constants.go

@@ -12,8 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// This file contains constants used by nogo binaries.
+// Note that this file is shared between the nogo binary and the builder.
+// Sharing it as a library isn't possible as libraries depend on nogo, creating
+// a circular dependency.
 package main
 
+// The exit codes for nogo binaries.
 const (
 	nogoSuccess int = iota
 	nogoError