docs: add documentation comments for method implementations and test utilities

- Add GoDoc for Warning.String, ParseError.Error
- Add GoDoc for ngxReqAPILayer.String, Phase.String, SocketState.String
- Add GoDoc for ConflictError.Error
- Add GoDoc for noopResolver methods (LookupHost, LookupHostWithCache, Refresh, Start, Stop, Stats)
- Add GoDoc for load balancer Select methods (roundRobin, weightedRoundRobin, ipHash)
- Add GoDoc for WithWSHeaders test utility
- Include author attribution (xfy)

internal/converter/nginx/converter.go

@@ -25,6 +25,7 @@ type Warning struct {
 	Message   string
 }
 
+// String 返回警告的字符串表示。
 func (w Warning) String() string {
 	return fmt.Sprintf("warning: %s:%d: %s", w.File, w.Line, w.Message)
 }

internal/converter/nginx/parser.go

@@ -28,6 +28,7 @@ type ParseError struct {
 	Message string
 }
 
+// Error 返回解析错误的字符串表示。
 func (e *ParseError) Error() string {
 	return fmt.Sprintf("%s:%d: %s", e.File, e.Line, e.Message)
 }

internal/e2e/testutil/websocket.go

@@ -38,6 +38,7 @@ type wsConfig struct {
 }
 
 // WithHeaders 设置请求头。
+// WithWSHeaders 设置 WebSocket 请求头。
 func WithWSHeaders(headers http.Header) WSOption {
 	return func(c *wsConfig) {
 		c.headers = headers

internal/lua/api_req.go

@@ -55,6 +55,7 @@ const (
 	layerStringUnknown = "unknown"
 )
 
+// String 返回 API 层级的字符串表示。
 func (l ngxReqAPILayer) String() string {
 	switch l {
 	case APILayerDirect:

internal/lua/coroutine.go

@@ -47,6 +47,7 @@ const (
 	PhaseBodyFilter
 )
 
+// String 返回处理阶段的字符串表示。
 func (p Phase) String() string {
 	switch p {
 	case PhaseInit:

internal/matcher/location.go

@@ -254,6 +254,7 @@ type ConflictError struct {
 	NewType      string
 }
 
+// Error 返回路径冲突错误的字符串表示。
 func (e *ConflictError) Error() string {
 	return fmt.Sprintf("path conflict: '%s' already registered as '%s', trying to register as '%s'",
 		e.Path, e.ExistingType, e.NewType)

internal/resolver/resolver.go

@@ -443,26 +443,34 @@ func (r *DNSResolver) Stats() Stats {
 // noopResolver 是禁用状态下的空实现。
 type noopResolver struct{}
 
+// LookupHost 解析主机名（空实现）。
+// 在禁用状态下返回错误。
 func (n *noopResolver) LookupHost(_ context.Context, _ string) ([]string, error) {
 	return nil, fmt.Errorf("resolver is disabled")
 }
 
+// LookupHostWithCache 带缓存解析主机名（空实现）。
+// 直接委托给 LookupHost。
 func (n *noopResolver) LookupHostWithCache(ctx context.Context, host string) ([]string, error) {
 	return n.LookupHost(ctx, host)
 }
 
+// Refresh 刷新解析器缓存（空实现）。
 func (n *noopResolver) Refresh(_ string) error {
 	return nil
 }
 
+// Start 启动解析器（空实现）。
 func (n *noopResolver) Start() error {
 	return nil
 }
 
+// Stop 停止解析器（空实现）。
 func (n *noopResolver) Stop() error {
 	return nil
 }
 
+// Stats 返回解析器统计信息（空实现）。
 func (n *noopResolver) Stats() Stats {
 	return Stats{}
 }

internal/stream/stream.go

@@ -79,6 +79,9 @@ func newRoundRobin() Balancer {
 	return rr
 }
 
+// Select 选择下一个目标（轮询算法）。
+//
+// 从健康目标列表中按轮询顺序选择。
 func (r *roundRobin) Select(targets []*Target) *Target {
 	// 从池中获取 healthy slice 并复用
 	healthyPtr := r.healthyPool.Get().(*[]*Target) //nolint:errcheck // pool always returns valid *[]*Target
@@ -168,6 +171,9 @@ func newWeightedRoundRobin() Balancer {
 	return w
 }
 
+// Select 选择下一个目标（加权轮询算法）。
+//
+// 从健康目标列表中按权重比例选择。
 func (w *weightedRoundRobin) Select(targets []*Target) *Target {
 	healthyPtr := w.healthyPool.Get().(*[]*Target) //nolint:errcheck // pool always returns valid *[]*Target
 	healthy := *healthyPtr
@@ -241,10 +247,17 @@ func newIPHash() Balancer {
 	return ih
 }
 
+// Select 选择下一个目标（IP 哈希算法）。
+//
+// 委托给 SelectByIP，使用空客户端 IP。
 func (i *ipHash) Select(targets []*Target) *Target {
 	return i.SelectByIP(targets, "")
 }
 
+// SelectByIP 根据客户端 IP 选择目标。
+//
+// 使用 FNV-64a 哈希算法对客户端 IP 进行哈希，从健康目标列表中选择对应的目标。
+// 如果 clientIP 为空，则回退到轮询选择。
 func (i *ipHash) SelectByIP(targets []*Target, clientIP string) *Target {
 	healthyPtr := i.healthyPool.Get().(*[]*Target) //nolint:errcheck // pool always returns valid *[]*Target
 	healthy := *healthyPtr