docs: add comments for all functions

sub/sub.go

@@ -1,3 +1,5 @@
+// Package sub provides subscription server functionality for the 3x-ui panel,
+// including HTTP/HTTPS servers for serving subscription links and JSON configurations.
 package sub
 
 import (
@@ -39,6 +41,7 @@ func setEmbeddedTemplates(engine *gin.Engine) error {
 	return nil
 }
 
+// Server represents the subscription server that serves subscription links and JSON configurations.
 type Server struct {
 	httpServer *http.Server
 	listener   net.Listener
@@ -50,6 +53,7 @@ type Server struct {
 	cancel context.CancelFunc
 }
 
+// NewServer creates a new subscription server instance with a cancellable context.
 func NewServer() *Server {
 	ctx, cancel := context.WithCancel(context.Background())
 	return &Server{
@@ -58,6 +62,8 @@ func NewServer() *Server {
 	}
 }
 
+// initRouter configures the subscription server's Gin engine, middleware,
+// templates and static assets and returns the ready-to-use engine.
 func (s *Server) initRouter() (*gin.Engine, error) {
 	// Always run in release mode for the subscription server
 	gin.DefaultWriter = io.Discard
@@ -222,6 +228,7 @@ func (s *Server) getHtmlFiles() ([]string, error) {
 	return files, nil
 }
 
+// Start initializes and starts the subscription server with configured settings.
 func (s *Server) Start() (err error) {
 	// This is an anonymous function, no function name
 	defer func() {
@@ -295,6 +302,7 @@ func (s *Server) Start() (err error) {
 	return nil
 }
 
+// Stop gracefully shuts down the subscription server and closes the listener.
 func (s *Server) Stop() error {
 	s.cancel()
 
@@ -309,6 +317,7 @@ 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
 }

sub/subController.go

@@ -10,6 +10,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// SUBController handles HTTP requests for subscription links and JSON configurations.
 type SUBController struct {
 	subTitle       string
 	subPath        string
@@ -22,6 +23,7 @@ type SUBController struct {
 	subJsonService *SubJsonService
 }
 
+// NewSUBController creates a new subscription controller with the given configuration.
 func NewSUBController(
 	g *gin.RouterGroup,
 	subPath string,
@@ -53,6 +55,8 @@ func NewSUBController(
 	return a
 }
 
+// initRouter registers HTTP routes for subscription links and JSON endpoints
+// on the provided router group.
 func (a *SUBController) initRouter(g *gin.RouterGroup) {
 	gLink := g.Group(a.subPath)
 	gLink.GET(":subid", a.subs)
@@ -62,6 +66,7 @@ func (a *SUBController) initRouter(g *gin.RouterGroup) {
 	}
 }
 
+// subs handles HTTP requests for subscription links, returning either HTML page or base64-encoded subscription data.
 func (a *SUBController) subs(c *gin.Context) {
 	subId := c.Param("subid")
 	scheme, host, hostWithPort, hostHeader := a.subService.ResolveRequest(c)
@@ -119,6 +124,7 @@ func (a *SUBController) subs(c *gin.Context) {
 	}
 }
 
+// subJsons handles HTTP requests for JSON subscription configurations.
 func (a *SUBController) subJsons(c *gin.Context) {
 	subId := c.Param("subid")
 	_, host, _, _ := a.subService.ResolveRequest(c)
@@ -134,6 +140,7 @@ func (a *SUBController) subJsons(c *gin.Context) {
 	}
 }
 
+// ApplyCommonHeaders sets common HTTP headers for subscription responses including user info, update interval, and profile title.
 func (a *SUBController) ApplyCommonHeaders(c *gin.Context, header, updateInterval, profileTitle string) {
 	c.Writer.Header().Set("Subscription-Userinfo", header)
 	c.Writer.Header().Set("Profile-Update-Interval", updateInterval)

sub/subJsonService.go

@@ -17,6 +17,7 @@ import (
 //go:embed default.json
 var defaultJson string
 
+// SubJsonService handles JSON subscription configuration generation and management.
 type SubJsonService struct {
 	configJson       map[string]any
 	defaultOutbounds []json_util.RawMessage
@@ -28,6 +29,7 @@ type SubJsonService struct {
 	SubService     *SubService
 }
 
+// NewSubJsonService creates a new JSON subscription service with the given configuration.
 func NewSubJsonService(fragment string, noises string, mux string, rules string, subService *SubService) *SubJsonService {
 	var configJson map[string]any
 	var defaultOutbounds []json_util.RawMessage
@@ -67,6 +69,7 @@ func NewSubJsonService(fragment string, noises string, mux string, rules string,
 	}
 }
 
+// GetJson generates a JSON subscription configuration for the given subscription ID and host.
 func (s *SubJsonService) GetJson(subId string, host string) (string, string, error) {
 	inbounds, err := s.SubService.getInboundsBySubId(subId)
 	if err != nil || len(inbounds) == 0 {

sub/subService.go

@@ -20,6 +20,7 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/xray"
 )
 
+// SubService provides business logic for generating subscription links and managing subscription data.
 type SubService struct {
 	address        string
 	showInfo       bool
@@ -29,6 +30,7 @@ type SubService struct {
 	settingService service.SettingService
 }
 
+// NewSubService creates a new subscription service with the given configuration.
 func NewSubService(showInfo bool, remarkModel string) *SubService {
 	return &SubService{
 		showInfo:    showInfo,
@@ -36,6 +38,7 @@ func NewSubService(showInfo bool, remarkModel string) *SubService {
 	}
 }
 
+// GetSubs retrieves subscription links for a given subscription ID and host.
 func (s *SubService) GetSubs(subId string, host string) ([]string, int64, xray.ClientTraffic, error) {
 	s.address = host
 	var result []string
@@ -1008,6 +1011,7 @@ func searchHost(headers any) string {
 }
 
 // PageData is a view model for subpage.html
+// PageData contains data for rendering the subscription information page.
 type PageData struct {
 	Host         string
 	BasePath     string
@@ -1029,6 +1033,7 @@ type PageData struct {
 }
 
 // ResolveRequest extracts scheme and host info from request/headers consistently.
+// ResolveRequest extracts scheme, host, and header information from an HTTP request.
 func (s *SubService) ResolveRequest(c *gin.Context) (scheme string, host string, hostWithPort string, hostHeader string) {
 	// scheme
 	scheme = "http"
@@ -1072,6 +1077,7 @@ func (s *SubService) ResolveRequest(c *gin.Context) (scheme string, host string,
 }
 
 // BuildURLs constructs absolute subscription and json URLs.
+// BuildURLs constructs subscription and JSON subscription URLs for a given subscription ID.
 func (s *SubService) BuildURLs(scheme, hostWithPort, subPath, subJsonPath, subId string) (subURL, subJsonURL string) {
 	if strings.HasSuffix(subPath, "/") {
 		subURL = scheme + "://" + hostWithPort + subPath + subId
@@ -1087,6 +1093,7 @@ func (s *SubService) BuildURLs(scheme, hostWithPort, subPath, subJsonPath, subId
 }
 
 // BuildPageData parses header and prepares the template view model.
+// BuildPageData constructs page data for rendering the subscription information page.
 func (s *SubService) BuildPageData(subId string, hostHeader string, traffic xray.ClientTraffic, lastOnline int64, subs []string, subURL, subJsonURL string) PageData {
 	download := common.FormatTraffic(traffic.Down)
 	upload := common.FormatTraffic(traffic.Up)