docs: add comments for all functions

7 files changed, 56 insertions, 0 deletions

diff --git a/xray/api.go b/xray/api.go
index d7ca4114..11119709 100644
--- a/xray/api.go
+++ b/xray/api.go
@@ -1,3 +1,6 @@
+// Package xray provides integration with the Xray proxy core.
+// It includes API client functionality, configuration management, traffic monitoring,
+// and process control for Xray instances.
 package xray
 
 import (
@@ -25,6 +28,7 @@ import (
 	"google.golang.org/grpc/credentials/insecure"
 )
 
+// XrayAPI is a gRPC client for managing Xray core configuration, inbounds, outbounds, and statistics.
 type XrayAPI struct {
 	HandlerServiceClient *command.HandlerServiceClient
 	StatsServiceClient   *statsService.StatsServiceClient
@@ -32,6 +36,7 @@ type XrayAPI struct {
 	isConnected          bool
 }
 
+// Init connects to the Xray API server and initializes handler and stats service clients.
 func (x *XrayAPI) Init(apiPort int) error {
 	if apiPort <= 0 || apiPort > math.MaxUint16 {
 		return fmt.Errorf("invalid Xray API port: %d", apiPort)
@@ -55,6 +60,7 @@ func (x *XrayAPI) Init(apiPort int) error {
 	return nil
 }
 
+// Close closes the gRPC connection and resets the XrayAPI client state.
 func (x *XrayAPI) Close() {
 	if x.grpcClient != nil {
 		x.grpcClient.Close()
@@ -64,6 +70,7 @@ func (x *XrayAPI) Close() {
 	x.isConnected = false
 }
 
+// AddInbound adds a new inbound configuration to the Xray core via gRPC.
 func (x *XrayAPI) AddInbound(inbound []byte) error {
 	client := *x.HandlerServiceClient
 
@@ -85,6 +92,7 @@ func (x *XrayAPI) AddInbound(inbound []byte) error {
 	return err
 }
 
+// DelInbound removes an inbound configuration from the Xray core by tag.
 func (x *XrayAPI) DelInbound(tag string) error {
 	client := *x.HandlerServiceClient
 	_, err := client.RemoveInbound(context.Background(), &command.RemoveInboundRequest{
@@ -93,6 +101,7 @@ func (x *XrayAPI) DelInbound(tag string) error {
 	return err
 }
 
+// AddUser adds a user to an inbound in the Xray core using the specified protocol and user data.
 func (x *XrayAPI) AddUser(Protocol string, inboundTag string, user map[string]any) error {
 	var account *serial.TypedMessage
 	switch Protocol {
@@ -153,6 +162,7 @@ func (x *XrayAPI) AddUser(Protocol string, inboundTag string, user map[string]an
 	return err
 }
 
+// RemoveUser removes a user from an inbound in the Xray core by email.
 func (x *XrayAPI) RemoveUser(inboundTag, email string) error {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
@@ -171,6 +181,7 @@ func (x *XrayAPI) RemoveUser(inboundTag, email string) error {
 	return nil
 }
 
+// GetTraffic queries traffic statistics from the Xray core, optionally resetting counters.
 func (x *XrayAPI) GetTraffic(reset bool) ([]*Traffic, []*ClientTraffic, error) {
 	if x.grpcClient == nil {
 		return nil, nil, common.NewError("xray api is not initialized")
@@ -205,6 +216,7 @@ func (x *XrayAPI) GetTraffic(reset bool) ([]*Traffic, []*ClientTraffic, error) {
 	return mapToSlice(tagTrafficMap), mapToSlice(emailTrafficMap), nil
 }
 
+// processTraffic aggregates a traffic stat into trafficMap using regex matches and value.
 func processTraffic(matches []string, value int64, trafficMap map[string]*Traffic) {
 	isInbound := matches[1] == "inbound"
 	tag := matches[2]
@@ -231,6 +243,7 @@ func processTraffic(matches []string, value int64, trafficMap map[string]*Traffi
 	}
 }
 
+// processClientTraffic updates clientTrafficMap with upload/download values for a client email.
 func processClientTraffic(matches []string, value int64, clientTrafficMap map[string]*ClientTraffic) {
 	email := matches[1]
 	isDown := matches[2] == "downlink"
@@ -248,6 +261,7 @@ func processClientTraffic(matches []string, value int64, clientTrafficMap map[st
 	}
 }
 
+// mapToSlice converts a map of pointers to a slice of pointers.
 func mapToSlice[T any](m map[string]*T) []*T {
 	result := make([]*T, 0, len(m))
 	for _, v := range m {
diff --git a/xray/client_traffic.go b/xray/client_traffic.go
index 84c509ac..4bb164d2 100644
--- a/xray/client_traffic.go
+++ b/xray/client_traffic.go
@@ -1,5 +1,7 @@
 package xray
 
+// ClientTraffic represents traffic statistics and limits for a specific client.
+// It tracks upload/download usage, expiry times, and online status for inbound clients.
 type ClientTraffic struct {
 	Id         int    `json:"id" form:"id" gorm:"primaryKey;autoIncrement"`
 	InboundId  int    `json:"inboundId" form:"inboundId"`
diff --git a/xray/config.go b/xray/config.go
index b10592d0..2b4a6673 100644
--- a/xray/config.go
+++ b/xray/config.go
@@ -6,6 +6,8 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/util/json_util"
 )
 
+// Config represents the complete Xray configuration structure.
+// It contains all sections of an Xray config file including inbounds, outbounds, routing, etc.
 type Config struct {
 	LogConfig        json_util.RawMessage `json:"log"`
 	RouterConfig     json_util.RawMessage `json:"routing"`
@@ -23,6 +25,7 @@ type Config struct {
 	Metrics          json_util.RawMessage `json:"metrics"`
 }
 
+// Equals compares two Config instances for deep equality.
 func (c *Config) Equals(other *Config) bool {
 	if len(c.InboundConfigs) != len(other.InboundConfigs) {
 		return false
diff --git a/xray/inbound.go b/xray/inbound.go
index 5a328f31..cbe4392d 100644
--- a/xray/inbound.go
+++ b/xray/inbound.go
@@ -6,6 +6,8 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/util/json_util"
 )
 
+// InboundConfig represents an Xray inbound configuration.
+// It defines how Xray accepts incoming connections including protocol, port, and settings.
 type InboundConfig struct {
 	Listen         json_util.RawMessage `json:"listen"` // listen cannot be an empty string
 	Port           int                  `json:"port"`
@@ -16,6 +18,7 @@ type InboundConfig struct {
 	Sniffing       json_util.RawMessage `json:"sniffing"`
 }
 
+// Equals compares two InboundConfig instances for deep equality.
 func (c *InboundConfig) Equals(other *InboundConfig) bool {
 	if !bytes.Equal(c.Listen, other.Listen) {
 		return false
diff --git a/xray/log_writer.go b/xray/log_writer.go
index 3be39b3e..b2b3b04a 100644
--- a/xray/log_writer.go
+++ b/xray/log_writer.go
@@ -8,14 +8,17 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/logger"
 )
 
+// NewLogWriter returns a new LogWriter for processing Xray log output.
 func NewLogWriter() *LogWriter {
 	return &LogWriter{}
 }
 
+// LogWriter processes and filters log output from the Xray process, handling crash detection and message filtering.
 type LogWriter struct {
 	lastLine string
 }
 
+// Write processes and filters log output from the Xray process, handling crash detection and message filtering.
 func (lw *LogWriter) Write(m []byte) (n int, err error) {
 	crashRegex := regexp.MustCompile(`(?i)(panic|exception|stack trace|fatal error)`)
 
diff --git a/xray/process.go b/xray/process.go
index 0df9c44b..f45d6cc9 100644
--- a/xray/process.go
+++ b/xray/process.go
@@ -18,46 +18,57 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/util/common"
 )
 
+// GetBinaryName returns the Xray binary filename for the current OS and architecture.
 func GetBinaryName() string {
 	return fmt.Sprintf("xray-%s-%s", runtime.GOOS, runtime.GOARCH)
 }
 
+// GetBinaryPath returns the full path to the Xray binary executable.
 func GetBinaryPath() string {
 	return config.GetBinFolderPath() + "/" + GetBinaryName()
 }
 
+// GetConfigPath returns the path to the Xray configuration file in the binary folder.
 func GetConfigPath() string {
 	return config.GetBinFolderPath() + "/config.json"
 }
 
+// GetGeositePath returns the path to the geosite data file used by Xray.
 func GetGeositePath() string {
 	return config.GetBinFolderPath() + "/geosite.dat"
 }
 
+// GetGeoipPath returns the path to the geoip data file used by Xray.
 func GetGeoipPath() string {
 	return config.GetBinFolderPath() + "/geoip.dat"
 }
 
+// GetIPLimitLogPath returns the path to the IP limit log file.
 func GetIPLimitLogPath() string {
 	return config.GetLogFolder() + "/3xipl.log"
 }
 
+// GetIPLimitBannedLogPath returns the path to the banned IP log file.
 func GetIPLimitBannedLogPath() string {
 	return config.GetLogFolder() + "/3xipl-banned.log"
 }
 
+// GetIPLimitBannedPrevLogPath returns the path to the previous banned IP log file.
 func GetIPLimitBannedPrevLogPath() string {
 	return config.GetLogFolder() + "/3xipl-banned.prev.log"
 }
 
+// GetAccessPersistentLogPath returns the path to the persistent access log file.
 func GetAccessPersistentLogPath() string {
 	return config.GetLogFolder() + "/3xipl-ap.log"
 }
 
+// GetAccessPersistentPrevLogPath returns the path to the previous persistent access log file.
 func GetAccessPersistentPrevLogPath() string {
 	return config.GetLogFolder() + "/3xipl-ap.prev.log"
 }
 
+// GetAccessLogPath reads the Xray config and returns the access log file path.
 func GetAccessLogPath() (string, error) {
 	config, err := os.ReadFile(GetConfigPath())
 	if err != nil {
@@ -82,14 +93,17 @@ func GetAccessLogPath() (string, error) {
 	return "", err
 }
 
+// stopProcess calls Stop on the given Process instance.
 func stopProcess(p *Process) {
 	p.Stop()
 }
 
+// Process wraps an Xray process instance and provides management methods.
 type Process struct {
 	*process
 }
 
+// NewProcess creates a new Xray process and sets up cleanup on garbage collection.
 func NewProcess(xrayConfig *Config) *Process {
 	p := &Process{newProcess(xrayConfig)}
 	runtime.SetFinalizer(p, stopProcess)
@@ -110,6 +124,7 @@ type process struct {
 	startTime time.Time
 }
 
+// newProcess creates a new internal process struct for Xray.
 func newProcess(config *Config) *process {
 	return &process{
 		version:   "Unknown",
@@ -119,6 +134,7 @@ func newProcess(config *Config) *process {
 	}
 }
 
+// IsRunning returns true if the Xray process is currently running.
 func (p *process) IsRunning() bool {
 	if p.cmd == nil || p.cmd.Process == nil {
 		return false
@@ -129,10 +145,12 @@ func (p *process) IsRunning() bool {
 	return false
 }
 
+// GetErr returns the last error encountered by the Xray process.
 func (p *process) GetErr() error {
 	return p.exitErr
 }
 
+// GetResult returns the last log line or error from the Xray process.
 func (p *process) GetResult() string {
 	if len(p.logWriter.lastLine) == 0 && p.exitErr != nil {
 		return p.exitErr.Error()
@@ -140,30 +158,37 @@ func (p *process) GetResult() string {
 	return p.logWriter.lastLine
 }
 
+// GetVersion returns the version string of the Xray process.
 func (p *process) GetVersion() string {
 	return p.version
 }
 
+// GetAPIPort returns the API port used by the Xray process.
 func (p *Process) GetAPIPort() int {
 	return p.apiPort
 }
 
+// GetConfig returns the configuration used by the Xray process.
 func (p *Process) GetConfig() *Config {
 	return p.config
 }
 
+// GetOnlineClients returns the list of online clients for the Xray process.
 func (p *Process) GetOnlineClients() []string {
 	return p.onlineClients
 }
 
+// SetOnlineClients sets the list of online clients for the Xray process.
 func (p *Process) SetOnlineClients(users []string) {
 	p.onlineClients = users
 }
 
+// GetUptime returns the uptime of the Xray process in seconds.
 func (p *Process) GetUptime() uint64 {
 	return uint64(time.Since(p.startTime).Seconds())
 }
 
+// refreshAPIPort updates the API port from the inbound configs.
 func (p *process) refreshAPIPort() {
 	for _, inbound := range p.config.InboundConfigs {
 		if inbound.Tag == "api" {
@@ -173,6 +198,7 @@ func (p *process) refreshAPIPort() {
 	}
 }
 
+// refreshVersion updates the version string by running the Xray binary with -version.
 func (p *process) refreshVersion() {
 	cmd := exec.Command(GetBinaryPath(), "-version")
 	data, err := cmd.Output()
@@ -188,6 +214,7 @@ func (p *process) refreshVersion() {
 	}
 }
 
+// Start launches the Xray process with the current configuration.
 func (p *process) Start() (err error) {
 	if p.IsRunning() {
 		return errors.New("xray is already running")
@@ -245,6 +272,7 @@ func (p *process) Start() (err error) {
 	return nil
 }
 
+// Stop terminates the running Xray process.
 func (p *process) Stop() error {
 	if !p.IsRunning() {
 		return errors.New("xray is not running")
@@ -257,6 +285,7 @@ func (p *process) Stop() error {
 	}
 }
 
+// writeCrashReport writes a crash report to the binary folder with a timestamped filename.
 func writeCrashReport(m []byte) error {
 	crashReportPath := config.GetBinFolderPath() + "/core_crash_" + time.Now().Format("20060102_150405") + ".log"
 	return os.WriteFile(crashReportPath, m, os.ModePerm)
diff --git a/xray/traffic.go b/xray/traffic.go
index 7b907bae..3547573c 100644
--- a/xray/traffic.go
+++ b/xray/traffic.go
@@ -1,5 +1,7 @@
 package xray
 
+// Traffic represents network traffic statistics for Xray connections.
+// It tracks upload and download bytes for inbound or outbound traffic.
 type Traffic struct {
 	IsInbound  bool
 	IsOutbound bool