docs: add comments for all functions

8 files changed, 29 insertions, 7 deletions

diff --git a/web/job/check_client_ip_job.go b/web/job/check_client_ip_job.go
index 7704e10d..e783a6df 100644
--- a/web/job/check_client_ip_job.go
+++ b/web/job/check_client_ip_job.go
@@ -18,6 +18,7 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/xray"
 )
 
+// CheckClientIpJob monitors client IP addresses from access logs and manages IP blocking based on configured limits.
 type CheckClientIpJob struct {
 	lastClear     int64
 	disAllowedIps []string
@@ -25,6 +26,7 @@ type CheckClientIpJob struct {
 
 var job *CheckClientIpJob
 
+// NewCheckClientIpJob creates a new client IP monitoring job instance.
 func NewCheckClientIpJob() *CheckClientIpJob {
 	job = new(CheckClientIpJob)
 	return job
diff --git a/web/job/check_cpu_usage.go b/web/job/check_cpu_usage.go
index 5cb9a21e..2ea87747 100644
--- a/web/job/check_cpu_usage.go
+++ b/web/job/check_cpu_usage.go
@@ -9,16 +9,18 @@ import (
 	"github.com/shirou/gopsutil/v4/cpu"
 )
 
+// CheckCpuJob monitors CPU usage and sends Telegram notifications when usage exceeds the configured threshold.
 type CheckCpuJob struct {
 	tgbotService   service.Tgbot
 	settingService service.SettingService
 }
 
+// NewCheckCpuJob creates a new CPU monitoring job instance.
 func NewCheckCpuJob() *CheckCpuJob {
 	return new(CheckCpuJob)
 }
 
-// Here run is a interface method of Job interface
+// Run checks CPU usage over the last minute and sends a Telegram alert if it exceeds the threshold.
 func (j *CheckCpuJob) Run() {
 	threshold, _ := j.settingService.GetTgCpu()
 
diff --git a/web/job/check_hash_storage.go b/web/job/check_hash_storage.go
index 5f826d63..2112079e 100644
--- a/web/job/check_hash_storage.go
+++ b/web/job/check_hash_storage.go
@@ -4,15 +4,17 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/web/service"
 )
 
+// CheckHashStorageJob periodically cleans up expired hash entries from the Telegram bot's hash storage.
 type CheckHashStorageJob struct {
 	tgbotService service.Tgbot
 }
 
+// NewCheckHashStorageJob creates a new hash storage cleanup job instance.
 func NewCheckHashStorageJob() *CheckHashStorageJob {
 	return new(CheckHashStorageJob)
 }
 
-// Here Run is an interface method of the Job interface
+// Run removes expired hash entries from the Telegram bot's hash storage.
 func (j *CheckHashStorageJob) Run() {
 	// Remove expired hashes from storage
 	j.tgbotService.GetHashStorage().RemoveExpiredHashes()
diff --git a/web/job/check_xray_running_job.go b/web/job/check_xray_running_job.go
index 8f5f0889..5b53b0c6 100644
--- a/web/job/check_xray_running_job.go
+++ b/web/job/check_xray_running_job.go
@@ -1,3 +1,5 @@
+// Package job provides background job implementations for the 3x-ui web panel,
+// including traffic monitoring, system checks, and periodic maintenance tasks.
 package job
 
 import (
@@ -5,16 +7,18 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/web/service"
 )
 
+// CheckXrayRunningJob monitors Xray process health and restarts it if it crashes.
 type CheckXrayRunningJob struct {
 	xrayService service.XrayService
-
-	checkTime int
+	checkTime   int
 }
 
+// NewCheckXrayRunningJob creates a new Xray health check job instance.
 func NewCheckXrayRunningJob() *CheckXrayRunningJob {
 	return new(CheckXrayRunningJob)
 }
 
+// Run checks if Xray has crashed and restarts it after confirming it's down for 2 consecutive checks.
 func (j *CheckXrayRunningJob) Run() {
 	if !j.xrayService.DidXrayCrash() {
 		j.checkTime = 0
diff --git a/web/job/clear_logs_job.go b/web/job/clear_logs_job.go
index 70e03688..85e0d64a 100644
--- a/web/job/clear_logs_job.go
+++ b/web/job/clear_logs_job.go
@@ -9,8 +9,10 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/xray"
 )
 
+// ClearLogsJob clears old log files to prevent disk space issues.
 type ClearLogsJob struct{}
 
+// NewClearLogsJob creates a new log cleanup job instance.
 func NewClearLogsJob() *ClearLogsJob {
 	return new(ClearLogsJob)
 }
diff --git a/web/job/periodic_traffic_reset_job.go b/web/job/periodic_traffic_reset_job.go
index 65aefb9d..6a370a51 100644
--- a/web/job/periodic_traffic_reset_job.go
+++ b/web/job/periodic_traffic_reset_job.go
@@ -5,19 +5,23 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/web/service"
 )
 
+// Period represents the time period for traffic resets.
 type Period string
 
+// PeriodicTrafficResetJob resets traffic statistics for inbounds based on their configured reset period.
 type PeriodicTrafficResetJob struct {
 	inboundService service.InboundService
 	period         Period
 }
 
+// NewPeriodicTrafficResetJob creates a new periodic traffic reset job for the specified period.
 func NewPeriodicTrafficResetJob(period Period) *PeriodicTrafficResetJob {
 	return &PeriodicTrafficResetJob{
 		period: period,
 	}
 }
 
+// Run resets traffic statistics for all inbounds that match the configured reset period.
 func (j *PeriodicTrafficResetJob) Run() {
 	inbounds, err := j.inboundService.GetInboundsByTrafficReset(string(j.period))
 	if err != nil {
diff --git a/web/job/stats_notify_job.go b/web/job/stats_notify_job.go
index 0d0907e0..b93f05cb 100644
--- a/web/job/stats_notify_job.go
+++ b/web/job/stats_notify_job.go
@@ -4,23 +4,26 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/web/service"
 )
 
+// LoginStatus represents the status of a login attempt.
 type LoginStatus byte
 
 const (
-	LoginSuccess LoginStatus = 1
-	LoginFail    LoginStatus = 0
+	LoginSuccess LoginStatus = 1 // Successful login
+	LoginFail    LoginStatus = 0 // Failed login attempt
 )
 
+// StatsNotifyJob sends periodic statistics reports via Telegram bot.
 type StatsNotifyJob struct {
 	xrayService  service.XrayService
 	tgbotService service.Tgbot
 }
 
+// NewStatsNotifyJob creates a new statistics notification job instance.
 func NewStatsNotifyJob() *StatsNotifyJob {
 	return new(StatsNotifyJob)
 }
 
-// Here run is a interface method of Job interface
+// Run sends a statistics report via Telegram bot if Xray is running.
 func (j *StatsNotifyJob) Run() {
 	if !j.xrayService.IsXrayRunning() {
 		return
diff --git a/web/job/xray_traffic_job.go b/web/job/xray_traffic_job.go
index 8ba5a9f9..a9affb4b 100644
--- a/web/job/xray_traffic_job.go
+++ b/web/job/xray_traffic_job.go
@@ -10,6 +10,7 @@ import (
 	"github.com/valyala/fasthttp"
 )
 
+// XrayTrafficJob collects and processes traffic statistics from Xray, updating the database and optionally informing external APIs.
 type XrayTrafficJob struct {
 	settingService  service.SettingService
 	xrayService     service.XrayService
@@ -17,10 +18,12 @@ type XrayTrafficJob struct {
 	outboundService service.OutboundService
 }
 
+// NewXrayTrafficJob creates a new traffic collection job instance.
 func NewXrayTrafficJob() *XrayTrafficJob {
 	return new(XrayTrafficJob)
 }
 
+// Run collects traffic statistics from Xray and updates the database, triggering restart if needed.
 func (j *XrayTrafficJob) Run() {
 	if !j.xrayService.IsXrayRunning() {
 		return