add Go doc comments to exported fields on flags.Config and globalfilter.Filter

Document every exported field in Config (flags package) and Filter,
NumericFilter, StringFilter (globalfilter package) with a concise one-line
doc comment describing its purpose and behaviour.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2 files changed, 75 insertions, 32 deletions

diff --git a/internal/flags/flags.go b/internal/flags/flags.go
index bbdf4b8..84f39e5 100644
--- a/internal/flags/flags.go
+++ b/internal/flags/flags.go
@@ -18,31 +18,59 @@ import (
 
 // Config captures runtime configuration parsed from CLI flags.
 type Config struct {
-	PidFilter    int
-	TidFilter    int
+	// PidFilter restricts tracing to the given process ID; -1 means no filter.
+	PidFilter int
+	// TidFilter restricts tracing to the given thread ID; -1 means no filter.
+	TidFilter int
+	// EventMapSize controls the BPF ring-buffer map size for kernel events.
 	EventMapSize int
-	CommFilter   string
-	PathFilter   string
-	PprofEnable  bool
-	Duration     int
-
-	// Tracepoints flags
-	TracepointsToAttach  []*regexp.Regexp
+	// CommFilter is a command-name substring filter applied at the CLI level.
+	CommFilter string
+	// PathFilter is a file-path substring filter applied at the CLI level.
+	PathFilter string
+	// PprofEnable turns on pprof profiling endpoints during the trace run.
+	PprofEnable bool
+	// Duration is the maximum tracing duration in seconds.
+	Duration int
+
+	// TracepointsToAttach is the list of compiled regexes that select which
+	// tracepoints to load; an empty list means attach all tracepoints.
+	TracepointsToAttach []*regexp.Regexp
+	// TracepointsToExclude is the list of compiled regexes that suppress
+	// specific tracepoints even when they match TracepointsToAttach.
 	TracepointsToExclude []*regexp.Regexp
 
-	// Output/runtime flags
-	PlainMode        bool
+	// PlainMode disables the TUI and writes raw CSV rows to stdout.
+	PlainMode bool
+	// FlamegraphOutput writes aggregated .ior.zst output for offline workflows.
 	FlamegraphOutput bool
-	ParquetPath      string
-	OutputName       string
-	TestFlames       bool
-	TestLiveFlames   bool
-	LiveInterval     time.Duration
-	TUIExportEnable  bool
-	CollapsedFields  []string
-	CountField       string
-	GlobalFilter     globalfilter.Filter
-	ResetTimer       time.Duration
+	// ParquetPath is the file path for writing all traced syscall rows to
+	// Parquet in headless mode; empty string disables Parquet output.
+	ParquetPath string
+	// OutputName is the base name used for .ior.zst trace output files.
+	OutputName string
+	// TestFlames runs the TUI with static synthetic flamegraph data for
+	// keyboard-navigation testing without a live BPF trace.
+	TestFlames bool
+	// TestLiveFlames runs the TUI with continuously-updating synthetic
+	// flamegraph data for live keyboard-navigation testing.
+	TestLiveFlames bool
+	// LiveInterval is the refresh interval for the synthetic live flamegraph
+	// used when TestLiveFlames is active.
+	LiveInterval time.Duration
+	// TUIExportEnable allows the TUI to write CSV snapshot export files.
+	TUIExportEnable bool
+	// CollapsedFields lists the event fields used as flamegraph collapse keys.
+	CollapsedFields []string
+	// CountField is the event field used as the numeric weight in flamegraph
+	// collapse aggregation.
+	CountField string
+	// GlobalFilter is the structured event filter applied across all dashboards
+	// and output modes; takes precedence over the individual CLI filter flags.
+	GlobalFilter globalfilter.Filter
+	// ResetTimer is the interval at which aggregate dashboard state (flamegraph
+	// trie and stats engine) is automatically cleared; 0 disables auto-reset.
+	ResetTimer time.Duration
 
 	// ShowVersion prints the banner plus version and exits without running.
 	ShowVersion bool
diff --git a/internal/globalfilter/filter.go b/internal/globalfilter/filter.go
index d55c4c1..afc2698 100644
--- a/internal/globalfilter/filter.go
+++ b/internal/globalfilter/filter.go
@@ -19,7 +19,9 @@ const (
 )
 
 type NumericFilter struct {
-	Op    CompareOp
+	// Op is the comparison operator applied when matching a candidate value.
+	Op CompareOp
+	// Value is the reference operand compared against the candidate value.
 	Value int64
 }
 
@@ -44,6 +46,8 @@ func (f *NumericFilter) EqValue() (int, bool) {
 }
 
 type StringFilter struct {
+	// Pattern is the substring (or anchored prefix/suffix) matched against the
+	// candidate string value; matching is case-insensitive.
 	Pattern string
 }
 
@@ -62,16 +66,27 @@ type Candidate interface {
 }
 
 type Filter struct {
-	Syscall    *StringFilter
-	Comm       *StringFilter
-	File       *StringFilter
-	PID        *NumericFilter
-	TID        *NumericFilter
-	FD         *NumericFilter
-	LatencyNs  *NumericFilter
-	GapNs      *NumericFilter
-	Bytes      *NumericFilter
-	RetVal     *NumericFilter
+	// Syscall filters events by syscall/tracepoint name substring.
+	Syscall *StringFilter
+	// Comm filters events by process command name substring.
+	Comm *StringFilter
+	// File filters events by the file path involved in the syscall.
+	File *StringFilter
+	// PID filters events by process ID using a numeric comparison.
+	PID *NumericFilter
+	// TID filters events by thread ID using a numeric comparison.
+	TID *NumericFilter
+	// FD filters events by file descriptor number using a numeric comparison.
+	FD *NumericFilter
+	// LatencyNs filters events by syscall latency in nanoseconds.
+	LatencyNs *NumericFilter
+	// GapNs filters events by inter-syscall gap duration in nanoseconds.
+	GapNs *NumericFilter
+	// Bytes filters events by the number of bytes transferred.
+	Bytes *NumericFilter
+	// RetVal filters events by the syscall return value.
+	RetVal *NumericFilter
+	// ErrorsOnly restricts the filter to events where the syscall returned an error.
 	ErrorsOnly bool
 }