Add doc comments to new passes API

passes.go

@@ -11,6 +11,7 @@ import (
 	"unsafe"
 )
 
+// PassBuilderOptions allows specifying several options for the PassBuilder.
 type PassBuilderOptions struct {
 	C C.LLVMPassBuilderOptionsRef
 }
@@ -33,7 +34,7 @@ func NewPassBuilderOptions() (pbo PassBuilderOptions) {
 //	default<O1>  -- run the default -O1 passes
 //	default<O2>  -- run the default -O2 passes
 //	default<O3>  -- run the default -O3 passes
-//	default<Os>  -- run the default -Os passes, like -O2 but size concious
+//	default<Os>  -- run the default -Os passes, like -O2 but size conscious
 //	default<Oz>  -- run the default -Oz passes, optimizing for size above all else
 func (mod Module) RunPasses(passes string, tm TargetMachine, options PassBuilderOptions) error {
 	cpasses := C.CString(passes)
@@ -51,51 +52,78 @@ func (mod Module) RunPasses(passes string, tm TargetMachine, options PassBuilder
 }
 
 // SetVerifyEach toggles adding a VerifierPass to the PassBuilder,
-// ensuring all functions inside the module are valid.
+// ensuring all functions inside the module are valid. Useful for
+// debugging, but adds a significant amount of overhead.
 func (pbo PassBuilderOptions) SetVerifyEach(verifyEach bool) {
 	C.LLVMPassBuilderOptionsSetVerifyEach(pbo.C, boolToLLVMBool(verifyEach))
 }
 
+// SetDebugLogging toggles debug logging for the PassBuilder.
 func (pbo PassBuilderOptions) SetDebugLogging(debugLogging bool) {
 	C.LLVMPassBuilderOptionsSetDebugLogging(pbo.C, boolToLLVMBool(debugLogging))
 }
 
+// SetLoopInterleaving toggles loop interleaving, which is part of
+// loop vectorization.
 func (pbo PassBuilderOptions) SetLoopInterleaving(loopInterleaving bool) {
 	C.LLVMPassBuilderOptionsSetLoopInterleaving(pbo.C, boolToLLVMBool(loopInterleaving))
 }
 
+// SetLoopVectorization toggles loop vectorization.
 func (pbo PassBuilderOptions) SetLoopVectorization(loopVectorization bool) {
 	C.LLVMPassBuilderOptionsSetLoopVectorization(pbo.C, boolToLLVMBool(loopVectorization))
 }
 
+// SetSLPVectorization toggles Super-Word Level Parallelism vectorization,
+// whose goal is to combine multiple similar independent instructions into
+// a vector instruction.
 func (pbo PassBuilderOptions) SetSLPVectorization(slpVectorization bool) {
 	C.LLVMPassBuilderOptionsSetSLPVectorization(pbo.C, boolToLLVMBool(slpVectorization))
 }
 
+// SetLoopUnrolling toggles loop unrolling.
 func (pbo PassBuilderOptions) SetLoopUnrolling(loopUnrolling bool) {
 	C.LLVMPassBuilderOptionsSetLoopUnrolling(pbo.C, boolToLLVMBool(loopUnrolling))
 }
 
+// SetForgetAllSCEVInLoopUnroll toggles forgetting all SCEV (Scalar Evolution)
+// information in loop unrolling. Scalar Evolution is a pass that analyses
+// the how scalars evolve over iterations of a loop in order to optimize
+// the loop better. Forgetting this information can be useful in some cases.
 func (pbo PassBuilderOptions) SetForgetAllSCEVInLoopUnroll(forgetSCEV bool) {
 	C.LLVMPassBuilderOptionsSetForgetAllSCEVInLoopUnroll(pbo.C, boolToLLVMBool(forgetSCEV))
 }
 
+// SetLicmMssaOptCap sets a tuning option to cap the number of calls to
+// retrieve clobbering accesses in MemorySSA, in Loop Invariant Code Motion
+// optimization.
+// See [llvm::PipelineTuningOptions::LicmMssaOptCap].
 func (pbo PassBuilderOptions) SetLicmMssaOptCap(optCap uint) {
 	C.LLVMPassBuilderOptionsSetLicmMssaOptCap(pbo.C, C.unsigned(optCap))
 }
 
+// SetLicmMssaNoAccForPromotionCap sets a tuning option to cap the number of
+// promotions to scalars in Loop Invariant Code Motion with MemorySSA, if
+// the number of accesses is too large.
+// See [llvm::PipelineTuningOptions::LicmMssaNoAccForPromotionCap].
 func (pbo PassBuilderOptions) SetLicmMssaNoAccForPromotionCap(promotionCap uint) {
 	C.LLVMPassBuilderOptionsSetLicmMssaNoAccForPromotionCap(pbo.C, C.unsigned(promotionCap))
 }
 
+// SetCallGraphProfile toggles whether call graph profiling should be used.
 func (pbo PassBuilderOptions) SetCallGraphProfile(cgProfile bool) {
 	C.LLVMPassBuilderOptionsSetCallGraphProfile(pbo.C, boolToLLVMBool(cgProfile))
 }
 
+// SetMergeFunctions toggles finding functions which will generate identical
+// machine code by considering all pointer types to be equivalent. Once
+// identified, they will be folded by replacing a call to one with a call to a
+// bitcast of the other.
 func (pbo PassBuilderOptions) SetMergeFunctions(mergeFuncs bool) {
 	C.LLVMPassBuilderOptionsSetMergeFunctions(pbo.C, boolToLLVMBool(mergeFuncs))
 }
 
+// Dispose of the memory allocated for the PassBuilderOptions.
 func (pbo PassBuilderOptions) Dispose() {
 	C.LLVMDisposePassBuilderOptions(pbo.C)
 }