refactor(tests,builder): remove dev-process metadata and filler from comments

- Strip Task/Phase number references from function and test comments
- Rewrite regression-guard language from past-tense to present-tense
- Remove "for now" filler phrases
- Update past-tense descriptions to present-tense design language

Improves signal-to-noise ratio in developer-facing comments without
changing technical content or intent.

Signed-off-by: Martin Wimpress <code@wimpress.io>

Author: flexiondotorg

generated_test.go

@@ -285,8 +285,8 @@ func TestGeneratorCharVsUint8(t *testing.T) {
 	list := ToCStr("test,foo,bar")
 	defer list.Free()
 
-	// If this compiles, the char→C.char mapping is working correctly
-	// (Previously this would fail: cannot use _Ctype_uint8_t as _Ctype_char)
+	// If this compiles, the char→C.char mapping is correct. A uint8_t
+	// regression would fail to compile: cannot use _Ctype_uint8_t as _Ctype_char.
 	result, err := AVMatchList(name, list, ',')
 	if err != nil {
 		t.Fatalf("AVMatchList failed: %v", err)
@@ -443,8 +443,8 @@ func TestGeneratorTypePreservation(t *testing.T) {
 // This validates the Priority 1 enhancement that enables enum/struct const arrays
 func TestGeneratorConstArrayFields(t *testing.T) {
 	t.Run("struct_const_array_AVRational", func(t *testing.T) {
-		// Test that struct const array fields work (AVRational[N])
-		// Previously skipped as "unknown const array"
+		// Test that struct const array fields work (AVRational[N]).
+		// Without const-array support these skip as "unknown const array".
 		// Example: AVDetectionBBox.classify_confidences (AVRational[4])
 
 		// Create a detection bbox (would normally come from av_detection_bbox_alloc)
@@ -456,8 +456,8 @@ func TestGeneratorConstArrayFields(t *testing.T) {
 	})
 
 	t.Run("enum_const_array", func(t *testing.T) {
-		// Test that enum const array fields work (AVEnum[N])
-		// Previously skipped as "unknown const array"
+		// Test that enum const array fields work (AVEnum[N]).
+		// Without const-array support these skip as "unknown const array".
 		// Example: AVDOVIReshapingCurve.mapping_idc (AVDOVIMappingMethod[8])
 
 		// Verify the accessor compiles by taking the method value;
@@ -468,9 +468,9 @@ func TestGeneratorConstArrayFields(t *testing.T) {
 	})
 
 	t.Run("byvalue_struct_array_helper", func(t *testing.T) {
-		// Test that ToXArray helpers are generated for ByValue structs
-		// Previously only generated for pointer structs
-		// This enables the array field accessors above to work
+		// Test that ToXArray helpers are generated for ByValue structs,
+		// not only pointer structs. This enables the array field accessors
+		// above to work.
 
 		// AVRational is a ByValue struct, should have ToAVRationalArray
 		r1 := AVMakeQ(1, 2)

image_test.go

@@ -5,7 +5,7 @@ import (
 	"unsafe"
 )
 
-// TestImagePlaneRoundTrip proves the Task 2.1 plane/linesize helper converts a
+// TestImagePlaneRoundTrip proves the plane/linesize helper converts a
 // four-plane set between Go slices and the fixed C [4] arrays without a cgocheck
 // abort. The plane pointers come from a C allocation (AVMalloc), mirroring how
 // real plane pointers originate from C-owned memory. Run under -race to exercise
@@ -43,7 +43,7 @@ func TestImagePlaneRoundTrip(t *testing.T) {
 	}
 }
 
-// TestAVImageAllocRoundTrip exercises the Task 2.2 alloc → fill → free path,
+// TestAVImageAllocRoundTrip exercises the alloc → fill → free path,
 // asserting dimensions and a balanced free.
 func TestAVImageAllocRoundTrip(t *testing.T) {
 	const (

internal/builder/main.go

@@ -504,7 +504,7 @@ func printLibraryList(libs []*Library) {
 		platform := getPlatformString(lib)
 		buildSys := getBuildSystemString(lib)
 
-		// Get link libs display string (without embedded colors for now)
+		// Link libs display string, without embedded colour codes
 		linkLibsDisplay := getLinkLibsString(lib)
 
 		// Color code based on library type

internal/generator/generator.go

@@ -436,8 +436,8 @@ type Generator struct {
 }
 
 // Gen runs the codegen pass. The skips collector is shared with Parse so a
-// single SkipCollector accumulates both parse-layer (Task 3.2) and codegen-layer
-// skips. A nil skips is tolerated: a fresh collector is allocated. The returned
+// single SkipCollector accumulates both parse-layer and codegen-layer skips.
+// A nil skips is tolerated: a fresh collector is allocated. The returned
 // collector is the active one (the argument when non-nil, otherwise the freshly
 // allocated one) so callers can read aggregated state without tracking it
 // separately.

internal/generator/generator_test.go

@@ -139,8 +139,8 @@ func TestMarshalReturnSkip(t *testing.T) {
 }
 
 // TestMarshalArgOutputPointerAllowlist pins the (function, parameter) allowlist
-// decision in marshalPointerArg. After Task 2.2 the allowlist is the only
-// output-pointer routing signal: a substring match like `width`, `size`, or
+// decision in marshalPointerArg. The allowlist is the only output-pointer
+// routing signal: a substring match like `width`, `size`, or
 // `_ptr` no longer keeps a parameter emittable on its own. This test asserts
 // that representative allowlisted pairs spanning the original heuristic
 // patterns still resolve to an emitted output pointer, and that near-miss
@@ -187,16 +187,15 @@ func TestMarshalArgOutputPointerAllowlist(t *testing.T) {
 	}
 }
 
-// TestMarshalArgPhase1OutputPointers pins the Phase 1 output-pointer table
-// additions: av_parse_time.timeval and av_get_output_timestamp.{dts,wall} are
-// pure-output int64_t* parameters now present in outputParams, so marshalArg
-// must emit them (skip == false) rather than record the former
-// "non-output primitive pointer" skip. Reintroducing the skip (by dropping the
-// table entry) flips skip to true here and trips the lowered skipCeiling in the
+// TestMarshalArgOutputPointers pins the output-pointer table entries:
+// av_parse_time.timeval and av_get_output_timestamp.{dts,wall} are pure-output
+// int64_t* parameters present in outputParams, so marshalArg must emit them
+// (skip == false) rather than record a "non-output primitive pointer" skip.
+// Dropping a table entry flips skip to true here and trips skipCeiling in the
 // generator run. av_expr_parse_and_eval.res is deliberately excluded: res is a
 // genuine output pointer, but the function stays skipped on its later
 // const char *const * params, so it never emits a callable binding.
-func TestMarshalArgPhase1OutputPointers(t *testing.T) {
+func TestMarshalArgOutputPointers(t *testing.T) {
 	g := skipGen()
 
 	tests := []struct {
@@ -213,7 +212,7 @@ func TestMarshalArgPhase1OutputPointers(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			if _, ok := outputParams[tt.fnName][tt.argName]; !ok {
-				t.Fatalf("outputParams[%q][%q] absent: Phase 1 table entry missing", tt.fnName, tt.argName)
+				t.Fatalf("outputParams[%q][%q] absent: output-pointer table entry missing", tt.fnName, tt.argName)
 			}
 
 			o := newFile()

internal/generator/main.go

@@ -16,33 +16,20 @@ import (
 // skipCeiling caps the total skip-marker count a clean generator run is
 // allowed to record. It is an upper bound (`count > skipCeiling` trips), not
 // an exact equality, so it acts as a regression ceiling rather than a brittle
-// target.
+// target: it tolerates a handful of legitimate per-symbol skips a future header
+// bump might introduce while still catching wholesale degradation, such as an
+// allowlist regression that drops dozens of bindings.
 //
-// The 231 baseline is the post-Phase-1 count: the output-pointer table gained
-// av_parse_time and av_get_output_timestamp, dropping two non-output-pointer
-// skips from the former 233. An upper bound tolerates a handful of legitimate
-// per-symbol skips a future header bump might introduce while still catching
-// wholesale degradation (e.g. an allowlist regression that drops dozens of
-// bindings).
+// The current count is the residue of shapes the generator cannot safely emit:
+// int32 matrix-pointer functions, the AVExifEntry union field, and the
+// fixed-size struct-array fields in the DRM descriptors
+// (AVDRMFrameDescriptor.objects/layers, AVDRMLayerDescriptor.planes). Most are
+// covered by hand-written bindings; the skip marker records that the generator
+// declined them, not that the symbol is unavailable.
 //
-// Bumping this constant is a curation decision. A legitimate FFmpeg upgrade
-// that introduces new unemittable symbols requires an intentional bump
-// alongside the header update; do not raise it to silence a regression.
-//
-// Bumped 231 -> 239 for the Tier 1 header promotion (ac3_parser, adts_parser,
-// avdct, dirac, dv_profile, vorbis_parser, md5): the newly bound headers carry
-// a handful of per-symbol unemittable shapes. This is an intentional curation
-// decision accompanying the allowlist expansion, not silencing a regression.
-//
-// Bumped 239 -> 245 for the Tier 2 header promotion (exif, hwcontext_drm): six
-// new per-symbol unemittable shapes land as recorded skips — two int32
-// matrix-pointer functions and the AVExifEntry union field from exif.h, plus
-// three fixed-size struct-array fields in the DRM descriptors
-// (AVDRMFrameDescriptor.objects/layers, AVDRMLayerDescriptor.planes). These are
-// deferred to a later hand-written-binding commit; the curation policy accepts
-// them as tracked skips, not a regression. (smpte_436m.h was evaluated for the
-// same tier but dropped: its symbols are absent from the FFmpeg 8.1.1 static
-// lib and would break the link.)
+// Bumping this constant is a curation decision. An FFmpeg upgrade that binds new
+// headers carrying unemittable shapes needs an intentional bump alongside the
+// header update; do not raise it to silence a regression.
 const skipCeiling = 245
 
 func main() {
@@ -74,13 +61,9 @@ func enforceSkipCeiling(total, ceiling int) error {
 
 // run drives one end-to-end generator pass: parse the FFmpeg headers, apply
 // the in-tree fixups, and emit the five `*.gen.go` files. It returns the skip
-// collector populated during emission so callers (main, tests, the Task 3.4
-// ceiling check) can inspect every `skipped due to ...` decision the run made.
+// collector populated during emission so callers (main, the ceiling check,
+// tests) can inspect every `skipped due to ...` decision the run made.
 //
-// The function is the single extraction point Task 3.1 added so the run path
-// is testable without invoking the package binary. summaryOut is reserved for
-// callers that want non-stderr toolchain logging; today only the verbose flag
-// touches it via log.SetOutput.
 // It exists as a separate function so the whole run path is testable without
 // invoking the package binary.
 func run(args []string) (*SkipCollector, error) {
@@ -184,8 +167,8 @@ func manualBindingBySymbol(c *SkipCollector) map[string]string {
 }
 
 // sortedUniqueSymbols returns the unique skipped symbol names in lexical
-// order. Used by the run summary and exposed for Task 3.4 to feed the same
-// list into the ceiling diagnostic when the cap trips.
+// order, feeding both the run summary and the ceiling diagnostic when the cap
+// trips.
 func sortedUniqueSymbols(c *SkipCollector) []string {
 	if c == nil {
 		return nil

internal/generator/parser.go

@@ -223,8 +223,8 @@ func sentinelParse() {
 
 // Parse drives the libclang parse over the pinned FFmpeg headers. The skips
 // collector is the same instance Gen receives, so parse-layer unhandled-shape
-// skips (Task 3.2) land in the run-summary alongside codegen-layer skips. A nil
-// skips is tolerated: SkipCollector.Record is nil-safe.
+// skips land in the run-summary alongside codegen-layer skips. A nil skips is
+// tolerated: SkipCollector.Record is nil-safe.
 func Parse(skips *SkipCollector) *Module {
 	p := &Parser{
 		mod: &Module{

internal/generator/parser_test.go

@@ -12,8 +12,8 @@ import (
 )
 
 // TestParseFunctionDuplicateAborts pins the invariant-violation panic at
-// parser.go:619 (duplicate function registration). Task 3.2 converted shape
-// panics to skip-with-reason but deliberately kept invariant panics fatal:
+// parser.go:619 (duplicate function registration). The parser converts shape
+// panics to skip-with-reason but deliberately keeps invariant panics fatal:
 // a duplicate registration means libclang misreported or the parser visited
 // the same FunctionDecl twice, so the bindings are untrustworthy and aborting
 // is correct. This test fabricates the duplicate by pre-seeding the module's

lib/fetch_test.go

@@ -115,9 +115,8 @@ func TestFindViaAPI_ReleaseSorting(t *testing.T) {
 		// Last element should be the "highest"
 		highest := sortedReleases[len(sortedReleases)-1]
 
-		// Note: lexicographic sorting means "lib-8.1.1.2" > "lib-8.1.1.10"
-		// This is a known limitation of the current implementation
-		// For now, we document the behavior
+		// Note: lexicographic sorting means "lib-8.1.1.2" > "lib-8.1.1.10",
+		// a known limitation of this sort.
 		t.Logf("Sorted releases: %v", sortedReleases)
 		t.Logf("Selected highest: %s", highest)
 

samples_test.go

@@ -4,7 +4,7 @@ import (
 	"testing"
 )
 
-// TestAVSamplesAllocSilenceRoundTrip exercises the Task 2.3 alloc → silence → free
+// TestAVSamplesAllocSilenceRoundTrip exercises the alloc → silence → free
 // path for a planar format, asserting a balanced free. Run under -race to exercise
 // cgocheck on the plane-pointer array scratch.
 func TestAVSamplesAllocSilenceRoundTrip(t *testing.T) {