From f464f30e6fbf59238e626fbdc2d53824d37685e9 Mon Sep 17 00:00:00 2001
From: John Guo <john@johng.cn>
Date: Mon, 16 Oct 2023 20:41:10 +0800
Subject: [PATCH] improve comment of router feature for ghttp.Server (#3014)

---
 net/ghttp/ghttp.go                     |  5 ++++-
 net/ghttp/ghttp_server_router.go       |  3 ++-
 net/ghttp/ghttp_server_router_serve.go | 12 ++++++++++++
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/net/ghttp/ghttp.go b/net/ghttp/ghttp.go
index 8a85eb040..3d1204271 100644
--- a/net/ghttp/ghttp.go
+++ b/net/ghttp/ghttp.go
@@ -87,7 +87,10 @@ type (
 	// HandlerItem is the registered handler for route handling,
 	// including middleware and hook functions.
 	HandlerItem struct {
-		Id         int             // Unique handler item id mark.
+		// Unique handler item id mark.
+		// Note that the handler function may be registered multiple times as different handler items,
+		// which have different handler item id.
+		Id         int
 		Name       string          // Handler name, which is automatically retrieved from runtime stack when registered.
 		Type       HandlerType     // Handler type: object/handler/middleware/hook.
 		Info       handlerFuncInfo // Handler function information.
diff --git a/net/ghttp/ghttp_server_router.go b/net/ghttp/ghttp_server_router.go
index 50da1e937..fbba732b4 100644
--- a/net/ghttp/ghttp_server_router.go
+++ b/net/ghttp/ghttp_server_router.go
@@ -207,7 +207,8 @@ func (s *Server) doSetHandler(
 	//    and the leaf node also has "*list" item. If the node is not a fuzzy node either
 	//    a leaf, it neither has "*list" item.
 	// 2. The "*list" item is a list containing registered router items ordered by their
-	//    priorities from high to low.
+	//    priorities from high to low. If it's a fuzzy node, all the sub router items
+	//    from this fuzzy node will also be added to its "*list" item.
 	// 3. There may be repeated router items in the router lists. The lists' priorities
 	//    from root to leaf are from low to high.
 	var p = s.serveTree[domain]
diff --git a/net/ghttp/ghttp_server_router_serve.go b/net/ghttp/ghttp_server_router_serve.go
index 4163d36aa..682c24da8 100644
--- a/net/ghttp/ghttp_server_router_serve.go
+++ b/net/ghttp/ghttp_server_router_serve.go
@@ -112,6 +112,7 @@ func (s *Server) searchHandlers(method, path, domain string) (parsedItems []*Han
 	)
 
 	// The default domain has the most priority when iteration.
+	// Please see doSetHandler if you want to get known about the structure of serveTree.
 	for _, domainItem := range []string{DefaultDomainName, domain} {
 		p, ok := s.serveTree[domainItem]
 		if !ok {
@@ -157,6 +158,17 @@ func (s *Server) searchHandlers(method, path, domain string) (parsedItems []*Han
 				item := e.Value.(*HandlerItem)
 				// Filter repeated handler items, especially the middleware and hook handlers.
 				// It is necessary, do not remove this checks logic unless you really know how it is necessary.
+				//
+				// The `repeatHandlerCheckMap` is used for repeat handler filtering during handler searching.
+				// As there are fuzzy nodes, and the fuzzy nodes have both sub-nodes and sub-list nodes, there
+				// may be repeated handler items in both sub-nodes and sub-list nodes. It here uses handler item id to
+				// identify the same handler item that registered.
+				//
+				// The same handler item is the one that is registered in the same function doSetHandler.
+				// Note that, one handler function(middleware or hook function) may be registered multiple times as
+				// different handler items using function doSetHandler, and they have different handler item id.
+				//
+				// Note that twice, the handler function may be registered multiple times as different handler items.
 				if _, isRepeatedHandler := repeatHandlerCheckMap[item.Id]; isRepeatedHandler {
 					continue
 				} else {