From 6ced549deaecb42b9bb93ea9efcb4c1bbaabe8a4 Mon Sep 17 00:00:00 2001
From: mhsanaei <ho3ein.sanaei@gmail.com>
Date: Sat, 20 Sep 2025 09:35:50 +0200
Subject: docs: add comments for all functions

---
 web/web.go | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

(limited to 'web/web.go')

diff --git a/web/web.go b/web/web.go
index daf312cb..c256112c 100644
--- a/web/web.go
+++ b/web/web.go
@@ -1,3 +1,5 @@
+// Package web provides the main web server implementation for the 3x-ui panel,
+// including HTTP/HTTPS serving, routing, templates, and background job scheduling.
 package web
 
 import (
@@ -78,15 +80,17 @@ func (f *wrapAssetsFileInfo) ModTime() time.Time {
 	return startTime
 }
 
-// Expose embedded resources for reuse by other servers (e.g., sub server)
+// EmbeddedHTML returns the embedded HTML templates filesystem for reuse by other servers.
 func EmbeddedHTML() embed.FS {
 	return htmlFS
 }
 
+// EmbeddedAssets returns the embedded assets filesystem for reuse by other servers.
 func EmbeddedAssets() embed.FS {
 	return assetsFS
 }
 
+// Server represents the main web server for the 3x-ui panel with controllers, services, and scheduled jobs.
 type Server struct {
 	httpServer *http.Server
 	listener   net.Listener
@@ -106,6 +110,7 @@ type Server struct {
 	cancel context.CancelFunc
 }
 
+// NewServer creates a new web server instance with a cancellable context.
 func NewServer() *Server {
 	ctx, cancel := context.WithCancel(context.Background())
 	return &Server{
@@ -114,6 +119,8 @@ func NewServer() *Server {
 	}
 }
 
+// getHtmlFiles walks the local `web/html` directory and returns a list of
+// template file paths. Used only in debug/development mode.
 func (s *Server) getHtmlFiles() ([]string, error) {
 	files := make([]string, 0)
 	dir, _ := os.Getwd()
@@ -133,6 +140,9 @@ func (s *Server) getHtmlFiles() ([]string, error) {
 	return files, nil
 }
 
+// getHtmlTemplate parses embedded HTML templates from the bundled `htmlFS`
+// using the provided template function map and returns the resulting
+// template set for production usage.
 func (s *Server) getHtmlTemplate(funcMap template.FuncMap) (*template.Template, error) {
 	t := template.New("").Funcs(funcMap)
 	err := fs.WalkDir(htmlFS, "html", func(path string, d fs.DirEntry, err error) error {
@@ -156,6 +166,8 @@ func (s *Server) getHtmlTemplate(funcMap template.FuncMap) (*template.Template,
 	return t, nil
 }
 
+// initRouter initializes Gin, registers middleware, templates, static
+// assets, controllers and returns the configured engine.
 func (s *Server) initRouter() (*gin.Engine, error) {
 	if config.IsDebug() {
 		gin.SetMode(gin.DebugMode)
@@ -259,6 +271,8 @@ func (s *Server) initRouter() (*gin.Engine, error) {
 	return engine, nil
 }
 
+// startTask schedules background jobs (Xray checks, traffic jobs, cron
+// jobs) which the panel relies on for periodic maintenance and monitoring.
 func (s *Server) startTask() {
 	err := s.xrayService.RestartXray(true)
 	if err != nil {
@@ -326,6 +340,7 @@ func (s *Server) startTask() {
 	}
 }
 
+// Start initializes and starts the web server with configured settings, routes, and background jobs.
 func (s *Server) Start() (err error) {
 	// This is an anonymous function, no function name
 	defer func() {
@@ -404,6 +419,7 @@ func (s *Server) Start() (err error) {
 	return nil
 }
 
+// Stop gracefully shuts down the web server, stops Xray, cron jobs, and Telegram bot.
 func (s *Server) Stop() error {
 	s.cancel()
 	s.xrayService.StopXray()
@@ -424,10 +440,12 @@ func (s *Server) Stop() error {
 	return common.Combine(err1, err2)
 }
 
+// GetCtx returns the server's context for cancellation and deadline management.
 func (s *Server) GetCtx() context.Context {
 	return s.ctx
 }
 
+// GetCron returns the server's cron scheduler instance.
 func (s *Server) GetCron() *cron.Cron {
 	return s.cron
 }
-- 
cgit v1.2.3