Merge pull request #18 from lvan100/main

optimizes code comments

Author: lvan100

gs/examples/bookman/.cover/cover.html

@@ -37,6 +37,10 @@ func init() {
 	gs.Banner(banner)
 }
 
+// init sets the working directory of the application to the directory
+// where this source file resides.
+// This ensures that any relative file operations are based on the source file location,
+// not the process launch path.
 func init() {
 	var execDir string
 	_, filename, _, ok := runtime.Caller(0)

gs/examples/bookman/README.md

@@ -37,6 +37,8 @@ func initRemoteConfig() error {
 	if err := getRemoteConfig(); err != nil {
 		return err
 	}
+	// Register a function job to refresh the configuration.
+	// A bean can be registered into the app during the bootstrap phase.
 	gs.FuncJob(refreshRemoteConfig)
 	return nil
 }
@@ -74,14 +76,18 @@ func getRemoteConfig() error {
 func refreshRemoteConfig(ctx context.Context) error {
 	for {
 		select {
-		case <-ctx.Done():
+		case <-ctx.Done(): // Gracefully exit when context is canceled.
+			// The context (ctx) is derived from the app instance.
+			// When the app exits, the context is canceled,
+			// allowing the loop to terminate gracefully.
 			fmt.Println("config updater exit")
 			return nil
 		case <-time.After(time.Millisecond * 500):
 			if err := getRemoteConfig(); err != nil {
 				fmt.Println("get remote config error:", err)
 				return err
 			}
+			// Refreshes the app configuration.
 			if err := gs.RefreshProperties(); err != nil {
 				fmt.Println("refresh properties error:", err)
 				return err

gs/examples/bookman/init.go

@@ -26,29 +26,43 @@ import (
 )
 
 func init() {
+	// Register a group of Bean definitions during application initialization.
+	// GroupRegister dynamically creates multiple Beans based on the configuration (conf.Properties),
+	// making it ideal for scenarios like setting up multiple loggers, clients, or resources from config.
 	gs.GroupRegister(func(p conf.Properties) ([]*gs.BeanDefinition, error) {
+
 		var loggers map[string]struct {
-			Name string `value:"${name}"`
-			Dir  string `value:"${dir}"`
+			Name string `value:"${name}"` // Log file name
+			Dir  string `value:"${dir}"`  // Directory where the log file will be stored
 		}
+
+		// Bind configuration from the "${log}" node into the 'loggers' map.
 		err := p.Bind(&loggers, "${log}")
 		if err != nil {
 			return nil, err
 		}
+
 		var ret []*gs.BeanDefinition
 		for k, l := range loggers {
 			var (
 				f    *os.File
 				flag = os.O_WRONLY | os.O_CREATE | os.O_APPEND
 			)
+
+			// Open (or create) the log file
 			f, err = os.OpenFile(filepath.Join(l.Dir, l.Name), flag, os.ModePerm)
 			if err != nil {
 				return nil, err
 			}
+
+			// Create a new slog.Logger instance with a text handler writing to the file
 			o := slog.New(slog.NewTextHandler(f, nil))
+
+			// Wrap the logger into a Bean with a destroy hook to close the file
 			b := gs.NewBean(o).Name(k).Destroy(func(_ *slog.Logger) {
 				_ = f.Close()
 			})
+
 			ret = append(ret, b)
 		}
 		return ret, nil

gs/examples/bookman/src/app/bootstrap/bootstrap.go

@@ -34,11 +34,13 @@ func init() {
 	)
 }
 
-// NewServeMux Creates a new HTTP request multiplexer and registers
+// NewServeMux creates a new HTTP request multiplexer and registers
 // routes with access logging middleware.
 func NewServeMux(c *controller.Controller, logger *slog.Logger) *http.ServeMux {
 	mux := http.NewServeMux()
 	proto.RegisterRouter(mux, c, Access(logger))
+
+	// Users can customize routes by adding handlers to the mux
 	mux.Handle("GET /", http.FileServer(http.Dir("./public")))
 	return mux
 }

gs/examples/bookman/src/app/common/handlers/log/log.go

@@ -24,6 +24,10 @@ func init() {
 	gs.Object(&Controller{})
 }
 
+// Controller implements the controller interface defined in the idl package.
+// In practice, controller methods can be grouped into different controllers.
+// Each sub-controller can have its own dependencies and be tested independently,
+// making the codebase more modular and maintainable.
 type Controller struct {
 	BookController
 }

gs/examples/bookman/src/app/common/httpsvr/httpsvr.go

@@ -34,11 +34,15 @@ type Job struct{}
 func (x *Job) Run(ctx context.Context) error {
 	for {
 		select {
-		case <-ctx.Done(): // Gracefully exit when context is canceled
+		case <-ctx.Done():
+			// Gracefully exit when the context is canceled
 			fmt.Println("job exit")
 			return nil
 		default:
-			if gs.Exiting() { // Check if the system is shutting down
+			// Check if the app is shutting down.
+			// In long-running background tasks, checking for shutdown signals
+			// during idle periods or between stages helps ensure timely resource cleanup.
+			if gs.Exiting() {
 				return nil
 			}
 			time.Sleep(time.Millisecond * 300)

gs/examples/bookman/src/app/controller/controller.go

@@ -14,12 +14,14 @@
  * limitations under the License.
  */
 
+// Package proto defines the interfaces and route registrations generated from IDL files.
 package proto
 
 import (
 	"net/http"
 )
 
+// Book represents the structure of a book entity.
 type Book struct {
 	Title       string `json:"title"`
 	Author      string `json:"author"`
@@ -29,13 +31,17 @@ type Book struct {
 	RefreshTime string `json:"refreshTime"`
 }
 
+// Controller defines the service interface for book-related operations.
 type Controller interface {
 	ListBooks(w http.ResponseWriter, r *http.Request)
 	GetBook(w http.ResponseWriter, r *http.Request)
 	SaveBook(w http.ResponseWriter, r *http.Request)
 	DeleteBook(w http.ResponseWriter, r *http.Request)
 }
 
+// RegisterRouter registers the HTTP routes for the Controller interface.
+// It maps each method to its corresponding HTTP endpoint,
+// and applies the given middleware (wrap) to each handler.
 func RegisterRouter(mux *http.ServeMux, c Controller, wrap func(next http.Handler) http.Handler) {
 	mux.Handle("GET /books", wrap(http.HandlerFunc(c.ListBooks)))
 	mux.Handle("GET /books/{isbn}", wrap(http.HandlerFunc(c.GetBook)))

gs/examples/bookman/src/biz/job/job.go

@@ -23,9 +23,17 @@ import (
 )
 
 func main() {
+	// Register an HTTP handler for the "/echo" endpoint.
 	http.HandleFunc("/echo", func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte("hello world!"))
 	})
+
+	// Start the Go-Spring framework.
+	// Compared to http.ListenAndServe, gs.Run() starts a full-featured application context with:
+	// - Auto Configuration: Automatically loads properties and beans.
+	// - Property Binding: Binds external configs (YAML, ENV) into structs.
+	// - Dependency Injection: Wires beans automatically.
+	// - Dynamic Refresh: Updates configs at runtime without restart.
 	gs.Run()
 }