Add comprehensive documentation to CLI components and core functionality

This commit extends the documentation effort by adding detailed explanatory
comments to key CLI components and core functionality throughout the cmd/
directory. The changes focus on explaining WHY certain logic is needed,
not just WHAT the code does, improving code maintainability and helping
developers understand complex business decisions.

Key improvements:
- Main entry points: Document CLI initialization, logging setup, and cache
  configuration with reasoning for design decisions
- DNS proxy core: Explain DNS proxy constants, data structures, and core
  processing pipeline for handling DNS queries
- Service management: Document service command structure, configuration
  patterns, and platform-specific service handling
- Logging infrastructure: Explain log buffer management, level encoders,
  and log formatting decisions for different use cases
- Metrics and monitoring: Document Prometheus metrics structure, HTTP
  endpoints, and conditional metric collection for performance
- Network handling: Explain Linux-specific network interface filtering,
  virtual interface detection, and DNS configuration management
- Hostname validation: Document RFC1123 compliance and DNS naming
  standards for system compatibility
- Mobile integration: Explain HTTP retry logic, fallback mechanisms, and
  mobile platform integration patterns
- Connection management: Document connection wrapper design to prevent
  log pollution during process lifecycle

Technical details:
- Added explanatory comments to 11 additional files in cmd/cli/
- Maintained consistent documentation style and format
- Preserved all existing functionality while improving code clarity
- Enhanced understanding of complex business logic and platform-specific
  behavior

These comments help future developers understand the reasoning behind
complex decisions, making the codebase more maintainable and reducing
the risk of incorrect modifications during maintenance.

cmd/cli/commands_service.go

@@ -10,6 +10,7 @@ import (
 )
 
 // filterEmptyStrings removes empty strings from a slice
+// This is used to clean up command line arguments and configuration values
 func filterEmptyStrings(slice []string) []string {
 	var result []string
 	for _, s := range slice {
@@ -21,17 +22,20 @@ func filterEmptyStrings(slice []string) []string {
 }
 
 // ServiceCommand handles service-related operations
+// This encapsulates all service management functionality for the CLI
 type ServiceCommand struct {
 	serviceManager *ServiceManager
 }
 
 // initializeServiceManager creates a service manager with default configuration
+// This sets up the basic service infrastructure needed for all service operations
 func (sc *ServiceCommand) initializeServiceManager() (service.Service, *prog, error) {
 	svcConfig := sc.createServiceConfig()
 	return sc.initializeServiceManagerWithServiceConfig(svcConfig)
 }
 
 // initializeServiceManagerWithServiceConfig creates a service manager with the given configuration
+// This allows for custom service configuration while maintaining the same initialization pattern
 func (sc *ServiceCommand) initializeServiceManagerWithServiceConfig(svcConfig *service.Config) (service.Service, *prog, error) {
 	p := &prog{}
 
@@ -45,6 +49,7 @@ func (sc *ServiceCommand) initializeServiceManagerWithServiceConfig(svcConfig *s
 }
 
 // newService creates a new service instance using the provided program and configuration.
+// This abstracts the service creation process for different operating systems
 func (sc *ServiceCommand) newService(p *prog, svcConfig *service.Config) (service.Service, error) {
 	s, err := newService(p, svcConfig)
 	if err != nil {
@@ -54,11 +59,13 @@ func (sc *ServiceCommand) newService(p *prog, svcConfig *service.Config) (servic
 }
 
 // NewServiceCommand creates a new service command handler
+// This provides a clean factory method for creating service command instances
 func NewServiceCommand() *ServiceCommand {
 	return &ServiceCommand{}
 }
 
 // createServiceConfig creates a properly initialized service configuration
+// This ensures consistent service naming and description across all platforms
 func (sc *ServiceCommand) createServiceConfig() *service.Config {
 	return &service.Config{
 		Name:        ctrldServiceName,
@@ -69,6 +76,7 @@ func (sc *ServiceCommand) createServiceConfig() *service.Config {
 }
 
 // InitServiceCmd creates the service command with proper logic and aliases
+// This sets up all service-related subcommands with appropriate permissions and flags
 func InitServiceCmd(rootCmd *cobra.Command) *cobra.Command {
 	// Create service command handlers
 	sc := NewServiceCommand()