docs: add comments for all functions

10 files changed, 35 insertions, 2 deletions

diff --git a/util/common/err.go b/util/common/err.go
index 85a743ad..e12bd13f 100644
--- a/util/common/err.go
+++ b/util/common/err.go
@@ -1,3 +1,4 @@
+// Package common provides common utility functions for error handling, formatting, and multi-error management.
 package common
 
 import (
@@ -7,16 +8,19 @@ import (
 	"github.com/mhsanaei/3x-ui/v2/logger"
 )
 
+// NewErrorf creates a new error with formatted message.
 func NewErrorf(format string, a ...any) error {
 	msg := fmt.Sprintf(format, a...)
 	return errors.New(msg)
 }
 
+// NewError creates a new error from the given arguments.
 func NewError(a ...any) error {
 	msg := fmt.Sprintln(a...)
 	return errors.New(msg)
 }
 
+// Recover handles panic recovery and logs the panic error if a message is provided.
 func Recover(msg string) any {
 	panicErr := recover()
 	if panicErr != nil {
diff --git a/util/common/format.go b/util/common/format.go
index c73e3a01..c40bd3dc 100644
--- a/util/common/format.go
+++ b/util/common/format.go
@@ -4,6 +4,7 @@ import (
 	"fmt"
 )
 
+// FormatTraffic formats traffic bytes into human-readable units (B, KB, MB, GB, TB, PB).
 func FormatTraffic(trafficBytes int64) string {
 	units := []string{"B", "KB", "MB", "GB", "TB", "PB"}
 	unitIndex := 0
diff --git a/util/common/multi_error.go b/util/common/multi_error.go
index ff9ff628..c695e3c0 100644
--- a/util/common/multi_error.go
+++ b/util/common/multi_error.go
@@ -4,8 +4,10 @@ import (
 	"strings"
 )
 
+// multiError represents a collection of errors.
 type multiError []error
 
+// Error returns a string representation of all errors joined with " | ".
 func (e multiError) Error() string {
 	var r strings.Builder
 	r.WriteString("multierr: ")
@@ -16,6 +18,7 @@ func (e multiError) Error() string {
 	return r.String()
 }
 
+// Combine combines multiple errors into a single error, filtering out nil errors.
 func Combine(maybeError ...error) error {
 	var errs multiError
 	for _, err := range maybeError {
diff --git a/util/crypto/crypto.go b/util/crypto/crypto.go
index f600e7a6..05d088a8 100644
--- a/util/crypto/crypto.go
+++ b/util/crypto/crypto.go
@@ -1,14 +1,17 @@
+// Package crypto provides cryptographic utilities for password hashing and verification.
 package crypto
 
 import (
 	"golang.org/x/crypto/bcrypt"
 )
 
+// HashPasswordAsBcrypt generates a bcrypt hash of the given password.
 func HashPasswordAsBcrypt(password string) (string, error) {
 	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
 	return string(hash), err
 }
 
+// CheckPasswordHash verifies if the given password matches the bcrypt hash.
 func CheckPasswordHash(hash, password string) bool {
 	err := bcrypt.CompareHashAndPassword([]byte(hash), []byte(password))
 	return err == nil
diff --git a/util/json_util/json.go b/util/json_util/json.go
index 54e3728a..d2d391bf 100644
--- a/util/json_util/json.go
+++ b/util/json_util/json.go
@@ -1,12 +1,15 @@
+// Package json_util provides JSON utilities including a custom RawMessage type.
 package json_util
 
 import (
 	"errors"
 )
 
+// RawMessage is a custom JSON raw message type that marshals empty slices as "null".
 type RawMessage []byte
 
-// MarshalJSON: Customize json.RawMessage default behavior
+// MarshalJSON customizes the JSON marshaling behavior for RawMessage.
+// Empty RawMessage values are marshaled as "null" instead of "[]".
 func (m RawMessage) MarshalJSON() ([]byte, error) {
 	if len(m) == 0 {
 		return []byte("null"), nil
@@ -14,7 +17,7 @@ func (m RawMessage) MarshalJSON() ([]byte, error) {
 	return m, nil
 }
 
-// UnmarshalJSON: sets *m to a copy of data.
+// UnmarshalJSON sets *m to a copy of the JSON data.
 func (m *RawMessage) UnmarshalJSON(data []byte) error {
 	if m == nil {
 		return errors.New("json.RawMessage: UnmarshalJSON on nil pointer")
diff --git a/util/random/random.go b/util/random/random.go
index 67ee0691..9610e26c 100644
--- a/util/random/random.go
+++ b/util/random/random.go
@@ -1,3 +1,4 @@
+// Package random provides utilities for generating random strings and numbers.
 package random
 
 import (
@@ -13,6 +14,8 @@ var (
 	allSeq      [62]rune
 )
 
+// init initializes the character sequences used for random string generation.
+// It sets up arrays for numbers, lowercase letters, uppercase letters, and combinations.
 func init() {
 	for i := 0; i < 10; i++ {
 		numSeq[i] = rune('0' + i)
@@ -33,6 +36,7 @@ func init() {
 	copy(allSeq[len(numSeq)+len(lowerSeq):], upperSeq[:])
 }
 
+// Seq generates a random string of length n containing alphanumeric characters (numbers, lowercase and uppercase letters).
 func Seq(n int) string {
 	runes := make([]rune, n)
 	for i := 0; i < n; i++ {
@@ -41,6 +45,7 @@ func Seq(n int) string {
 	return string(runes)
 }
 
+// Num generates a random integer between 0 and n-1.
 func Num(n int) int {
 	return rand.Intn(n)
 }
diff --git a/util/reflect_util/reflect.go b/util/reflect_util/reflect.go
index 1fdaec50..1f557e0d 100644
--- a/util/reflect_util/reflect.go
+++ b/util/reflect_util/reflect.go
@@ -1,7 +1,9 @@
+// Package reflect_util provides reflection utilities for working with struct fields and values.
 package reflect_util
 
 import "reflect"
 
+// GetFields returns all struct fields of the given reflect.Type.
 func GetFields(t reflect.Type) []reflect.StructField {
 	num := t.NumField()
 	fields := make([]reflect.StructField, 0, num)
@@ -11,6 +13,7 @@ func GetFields(t reflect.Type) []reflect.StructField {
 	return fields
 }
 
+// GetFieldValues returns all field values of the given reflect.Value.
 func GetFieldValues(v reflect.Value) []reflect.Value {
 	num := v.NumField()
 	fields := make([]reflect.Value, 0, num)
diff --git a/util/sys/psutil.go b/util/sys/psutil.go
index 3d7cac80..98adf775 100644
--- a/util/sys/psutil.go
+++ b/util/sys/psutil.go
@@ -1,3 +1,5 @@
+// Package sys provides system utilities for monitoring network connections and CPU usage.
+// Platform-specific implementations are provided for Windows, Linux, and macOS.
 package sys
 
 import (
diff --git a/util/sys/sys_linux.go b/util/sys/sys_linux.go
index 8a494d62..23483b57 100644
--- a/util/sys/sys_linux.go
+++ b/util/sys/sys_linux.go
@@ -45,6 +45,8 @@ func getLinesNum(filename string) (int, error) {
 	return sum, nil
 }
 
+// GetTCPCount returns the number of active TCP connections by reading
+// /proc/net/tcp and /proc/net/tcp6 when available.
 func GetTCPCount() (int, error) {
 	root := HostProc()
 
@@ -75,6 +77,8 @@ func GetUDPCount() (int, error) {
 	return udp4 + udp6, nil
 }
 
+// safeGetLinesNum returns 0 if the file does not exist, otherwise forwards
+// to getLinesNum to count the number of lines.
 func safeGetLinesNum(path string) (int, error) {
 	if _, err := os.Stat(path); os.IsNotExist(err) {
 		return 0, nil
diff --git a/util/sys/sys_windows.go b/util/sys/sys_windows.go
index f3eae076..186fa4bb 100644
--- a/util/sys/sys_windows.go
+++ b/util/sys/sys_windows.go
@@ -12,6 +12,7 @@ import (
 	"github.com/shirou/gopsutil/v4/net"
 )
 
+// GetConnectionCount returns the number of active connections for the specified protocol ("tcp" or "udp").
 func GetConnectionCount(proto string) (int, error) {
 	if proto != "tcp" && proto != "udp" {
 		return 0, errors.New("invalid protocol")
@@ -24,10 +25,12 @@ func GetConnectionCount(proto string) (int, error) {
 	return len(stats), nil
 }
 
+// GetTCPCount returns the number of active TCP connections.
 func GetTCPCount() (int, error) {
 	return GetConnectionCount("tcp")
 }
 
+// GetUDPCount returns the number of active UDP connections.
 func GetUDPCount() (int, error) {
 	return GetConnectionCount("udp")
 }
@@ -50,6 +53,8 @@ type filetime struct {
 	HighDateTime uint32
 }
 
+// ftToUint64 converts a Windows FILETIME-like struct to a uint64 for
+// arithmetic and delta calculations used by CPUPercentRaw.
 func ftToUint64(ft filetime) uint64 {
 	return (uint64(ft.HighDateTime) << 32) | uint64(ft.LowDateTime)
 }