docs: add missing godoc comments for exported APIs (task 382)

4 files changed, 19 insertions, 0 deletions

diff --git a/internal/event/event.go b/internal/event/event.go
index c2c9aea..48bde48 100644
--- a/internal/event/event.go
+++ b/internal/event/event.go
@@ -10,6 +10,7 @@ var poolOfEventPairs = sync.Pool{
 	New: func() interface{} { return &Pair{} },
 }
 
+// Event is the common contract implemented by decoded syscall trace events.
 type Event interface {
 	String() string
 	GetTraceId() types.TraceId
diff --git a/internal/file/file.go b/internal/file/file.go
index 83c690a..b95d40b 100644
--- a/internal/file/file.go
+++ b/internal/file/file.go
@@ -11,6 +11,7 @@ import (
 	"ior/internal/types"
 )
 
+// File is the common interface for file-like syscall payload representations.
 type File interface {
 	String() string
 	Name() string
@@ -18,6 +19,7 @@ type File interface {
 	FD() int32
 }
 
+// FdFile represents a file descriptor-backed file reference.
 type FdFile struct {
 	fd              int32
 	name            string
@@ -25,6 +27,7 @@ type FdFile struct {
 	flagsFromProcFS bool
 }
 
+// NewFd constructs an FdFile from explicit descriptor metadata.
 func NewFd(fd int32, name string, flags int32) *FdFile {
 	f := &FdFile{
 		fd:    fd,
@@ -37,6 +40,7 @@ func NewFd(fd int32, name string, flags int32) *FdFile {
 	return f
 }
 
+// NewFdWithPid resolves descriptor metadata from /proc/<pid>/fd.
 func NewFdWithPid(fd int32, pid uint32) *FdFile {
 	f := &FdFile{
 		fd: fd,
@@ -122,6 +126,7 @@ type oldnameNewnameFile struct {
 	Oldname, Newname string
 }
 
+// NewOldnameNewname creates a file representation for rename-like syscalls.
 func NewOldnameNewname(oldname, newname []byte) oldnameNewnameFile {
 	return oldnameNewnameFile{types.StringValue(oldname), types.StringValue(newname)}
 }
@@ -156,6 +161,7 @@ type pathnameFile struct {
 	Pathname string
 }
 
+// NewPathname creates a path-only file representation.
 func NewPathname(pathname []byte) pathnameFile {
 	return pathnameFile{types.StringValue(pathname)}
 }
diff --git a/internal/flags/flags.go b/internal/flags/flags.go
index f1285e8..af8f84c 100644
--- a/internal/flags/flags.go
+++ b/internal/flags/flags.go
@@ -25,6 +25,7 @@ func init() {
 	current.Store(&defaults)
 }
 
+// Config captures runtime configuration parsed from CLI flags.
 type Config struct {
 	PidFilter    int
 	TidFilter    int
@@ -85,6 +86,7 @@ func (f Config) clone() Config {
 	return out
 }
 
+// Get returns a copy of the currently active runtime configuration.
 func Get() Config {
 	cfg := current.Load()
 	if cfg == nil {
@@ -134,6 +136,7 @@ func SetTUIExportEnable(enabled bool) {
 	})
 }
 
+// Parse parses CLI flags once and updates the current runtime configuration.
 func Parse() error {
 	once.Do(func() {
 		parseErr = parse()
diff --git a/internal/probemanager/manager.go b/internal/probemanager/manager.go
index b991c7c..7feb407 100644
--- a/internal/probemanager/manager.go
+++ b/internal/probemanager/manager.go
@@ -50,6 +50,7 @@ type Manager struct {
 	closed   bool
 }
 
+// NewManager creates a new probe manager that resolves programs via attacher.
 func NewManager(attacher Attacher) *Manager {
 	return &Manager{
 		attacher: attacher,
@@ -57,6 +58,7 @@ func NewManager(attacher Attacher) *Manager {
 	}
 }
 
+// Register registers the enter/exit tracepoint pair for a syscall key.
 func (m *Manager) Register(syscall string, pair TracepointPair) {
 	if m == nil || syscall == "" {
 		return
@@ -74,6 +76,7 @@ func (m *Manager) Register(syscall string, pair TracepointPair) {
 	entry.exitTP = pair.Exit
 }
 
+// AttachAll registers and attaches all tracepoint pairs selected by shouldAttach.
 func (m *Manager) AttachAll(shouldAttach func(string) bool, tpNames []string) error {
 	if m == nil {
 		return errors.New("probe manager is nil")
@@ -95,6 +98,7 @@ func (m *Manager) AttachAll(shouldAttach func(string) bool, tpNames []string) er
 	return nil
 }
 
+// Toggle flips a syscall probe between attached and detached states.
 func (m *Manager) Toggle(syscall string) error {
 	if m == nil {
 		return errors.New("probe manager is nil")
@@ -118,6 +122,7 @@ func (m *Manager) Toggle(syscall string) error {
 	return m.Attach(syscall)
 }
 
+// Attach attaches enter/exit tracepoints for a registered syscall.
 func (m *Manager) Attach(syscall string) error {
 	if syscall == "" {
 		return errors.New("syscall is required")
@@ -167,6 +172,7 @@ func (m *Manager) Attach(syscall string) error {
 	return nil
 }
 
+// Detach detaches enter/exit tracepoints for a registered syscall.
 func (m *Manager) Detach(syscall string) error {
 	if syscall == "" {
 		return errors.New("syscall is required")
@@ -220,6 +226,7 @@ func (m *Manager) Detach(syscall string) error {
 	return combined
 }
 
+// States returns a stable snapshot of all known probe states.
 func (m *Manager) States() []ProbeState {
 	if m == nil {
 		return nil
@@ -243,6 +250,7 @@ func (m *Manager) States() []ProbeState {
 	return out
 }
 
+// ActiveCount returns the number of active probes and total registered probes.
 func (m *Manager) ActiveCount() (active, total int) {
 	if m == nil {
 		return 0, 0
@@ -276,6 +284,7 @@ func (m *Manager) IsActive(syscall string) bool {
 	return entry.active
 }
 
+// Close detaches all registered probes and marks the manager closed.
 func (m *Manager) Close() error {
 	if m == nil {
 		return nil