feat(cmd/gf): add controller comment support for command gf gen ctrl (#4169)

cmd/gf/internal/cmd/genctrl/genctrl_api_item.go

@@ -6,7 +6,11 @@
 
 package genctrl
 
-import "github.com/gogf/gf/v2/text/gstr"
+import (
+	"fmt"
+
+	"github.com/gogf/gf/v2/text/gstr"
+)
 
 type apiItem struct {
 	Import     string `eg:"demo.com/api/user/v1"`
@@ -14,6 +18,7 @@ type apiItem struct {
 	Module     string `eg:"user"`
 	Version    string `eg:"v1"`
 	MethodName string `eg:"GetList"`
+	Comment    string `eg:"GetList get list"`
 }
 
 func (a apiItem) String() string {
@@ -21,3 +26,12 @@ func (a apiItem) String() string {
 		a.Import, a.Module, a.Version, a.MethodName,
 	}, ",")
 }
+
+// GetComment returns the comment of apiItem.
+func (a apiItem) GetComment() string {
+	if a.Comment == "" {
+		return ""
+	}
+	// format for handling comments
+	return fmt.Sprintf("\n// %s %s", a.MethodName, a.Comment)
+}

cmd/gf/internal/cmd/genctrl/genctrl_ast_parse.go

@@ -17,9 +17,14 @@ import (
 	"github.com/gogf/gf/v2/text/gstr"
 )
 
-// getStructsNameInSrc retrieves all struct names
+type structInfo struct {
+	structName string
+	comment    string
+}
+
+// getStructsNameInSrc retrieves all struct names and comment
 // that end in "Req" and have "g.Meta" in their body.
-func (c CGenCtrl) getStructsNameInSrc(filePath string) (structsName []string, err error) {
+func (c CGenCtrl) getStructsNameInSrc(filePath string) (structInfos []*structInfo, err error) {
 	var (
 		fileContent = gfile.GetContents(filePath)
 		fileSet     = token.NewFileSet()
@@ -32,8 +37,8 @@ func (c CGenCtrl) getStructsNameInSrc(filePath string) (structsName []string, er
 
 	ast.Inspect(node, func(n ast.Node) bool {
 		if typeSpec, ok := n.(*ast.TypeSpec); ok {
-			methodName := typeSpec.Name.Name
+			structName := typeSpec.Name.Name
-			if !gstr.HasSuffix(methodName, "Req") {
+			if !gstr.HasSuffix(structName, "Req") {
 				// ignore struct name that do not end in "Req"
 				return true
 			}
@@ -46,7 +51,19 @@ func (c CGenCtrl) getStructsNameInSrc(filePath string) (structsName []string, er
 				if !gstr.Contains(buf.String(), `g.Meta`) {
 					return true
 				}
-				structsName = append(structsName, methodName)
+
+				comment := typeSpec.Doc.Text()
+				// remove the struct name from the comment
+				if gstr.HasPrefix(comment, structName) {
+					comment = gstr.TrimLeftStr(comment, structName, 1)
+				}
+				// remove the comment \n or space
+				comment = gstr.Trim(comment)
+
+				structInfos = append(structInfos, &structInfo{
+					structName: structName,
+					comment:    comment,
+				})
 			}
 		}
 		return true

cmd/gf/internal/cmd/genctrl/genctrl_calculate.go

@@ -39,15 +39,16 @@ func (c CGenCtrl) getApiItemsInSrc(apiModuleFolderPath string) (items []apiItem,
 			if err != nil {
 				return nil, err
 			}
-			for _, methodName := range structsInfo {
+			for _, s := range structsInfo {
 				// remove end "Req"
-				methodName = gstr.TrimRightStr(methodName, "Req", 1)
+				methodName := gstr.TrimRightStr(s.structName, "Req", 1)
 				item := apiItem{
 					Import:     gstr.Trim(importPath, `"`),
 					FileName:   gfile.Name(apiFileFolderPath),
 					Module:     gfile.Basename(apiModuleFolderPath),
 					Version:    gfile.Basename(apiVersionFolderPath),
 					MethodName: methodName,
+					Comment:    s.comment,
 				}
 				items = append(items, item)
 			}

cmd/gf/internal/cmd/genctrl/genctrl_generate_ctrl.go

@@ -138,10 +138,11 @@ func (c *controllerGenerator) doGenerateCtrlItem(dstModuleFolderPath string, ite
 
 	if gfile.Exists(methodFilePath) {
 		content = gstr.ReplaceByMap(consts.TemplateGenCtrlControllerMethodFuncMerge, g.MapStrStr{
-			"{Module}":     item.Module,
+			"{Module}":        item.Module,
-			"{CtrlName}":   ctrlName,
+			"{CtrlName}":      ctrlName,
-			"{Version}":    item.Version,
+			"{Version}":       item.Version,
-			"{MethodName}": item.MethodName,
+			"{MethodName}":    item.MethodName,
+			"{MethodComment}": item.GetComment(),
 		})
 
 		if gstr.Contains(gfile.GetContents(methodFilePath), fmt.Sprintf(`func (c *%v) %v(`, ctrlName, item.MethodName)) {
@@ -152,11 +153,12 @@ func (c *controllerGenerator) doGenerateCtrlItem(dstModuleFolderPath string, ite
 		}
 	} else {
 		content = gstr.ReplaceByMap(consts.TemplateGenCtrlControllerMethodFunc, g.MapStrStr{
-			"{Module}":     item.Module,
+			"{Module}":        item.Module,
-			"{ImportPath}": item.Import,
+			"{ImportPath}":    item.Import,
-			"{CtrlName}":   ctrlName,
+			"{CtrlName}":      ctrlName,
-			"{Version}":    item.Version,
+			"{Version}":       item.Version,
-			"{MethodName}": item.MethodName,
+			"{MethodName}":    item.MethodName,
+			"{MethodComment}": item.GetComment(),
 		})
 		if err = gfile.PutContents(methodFilePath, gstr.TrimLeft(content)); err != nil {
 			return err
@@ -192,10 +194,11 @@ func (c *controllerGenerator) doGenerateCtrlMergeItem(dstModuleFolderPath string
 		}
 
 		ctrl := gstr.TrimLeft(gstr.ReplaceByMap(consts.TemplateGenCtrlControllerMethodFuncMerge, g.MapStrStr{
-			"{Module}":     api.Module,
+			"{Module}":        api.Module,
-			"{CtrlName}":   fmt.Sprintf(`Controller%s`, gstr.UcFirst(api.Version)),
+			"{CtrlName}":      fmt.Sprintf(`Controller%s`, gstr.UcFirst(api.Version)),
-			"{Version}":    api.Version,
+			"{Version}":       api.Version,
-			"{MethodName}": api.MethodName,
+			"{MethodName}":    api.MethodName,
+			"{MethodComment}": api.GetComment(),
 		}))
 		ctrlFileItem.controllers.WriteString(ctrl)
 		doneApiSet.Add(api.String())

cmd/gf/internal/cmd/genctrl/genctrl_generate_sdk.go

@@ -180,6 +180,7 @@ func (c *apiSdkGenerator) doGenerateSdkImplementer(
 			"{Version}":         item.Version,
 			"{MethodName}":      item.MethodName,
 			"{ImplementerName}": implementerName,
+			"{MethodComment}":   item.GetComment(),
 		}))
 		implementerFileContent += "\n"
 	}

cmd/gf/internal/cmd/testdata/genctrl/api/article/v1/edit.go

@@ -9,6 +9,7 @@ package v1
 import "github.com/gogf/gf/v2/frame/g"
 
 type (
+	// CreateReq add title.
 	CreateReq struct {
 		g.Meta `path:"/article/create" method:"post" tags:"ArticleService"`
 		Title  string `v:"required"`

cmd/gf/internal/cmd/testdata/genctrl/controller/article/article_v1_create.go

@@ -9,6 +9,7 @@ import (
 	"github.com/gogf/gf/cmd/gf/v2/internal/cmd/testdata/genctrl/api/article/v1"
 )
 
+// Create add title.
 func (c *ControllerV1) Create(ctx context.Context, req *v1.CreateReq) (res *v1.CreateRes, err error) {
 	return nil, gerror.NewCode(gcode.CodeNotImplemented)
 }

cmd/gf/internal/consts/consts_gen_ctrl_template.go

@@ -45,7 +45,7 @@ import (
 
 	"{ImportPath}"
 )
-
+{MethodComment}
 func (c *{CtrlName}) {MethodName}(ctx context.Context, req *{Version}.{MethodName}Req) (res *{Version}.{MethodName}Res, err error) {
 	return nil, gerror.NewCode(gcode.CodeNotImplemented)
 }
@@ -66,7 +66,7 @@ import (
 `
 
 const TemplateGenCtrlControllerMethodFuncMerge = `
-
+{MethodComment}
 func (c *{CtrlName}) {MethodName}(ctx context.Context, req *{Version}.{MethodName}Req) (res *{Version}.{MethodName}Res, err error) {
 	return nil, gerror.NewCode(gcode.CodeNotImplemented)
 }

cmd/gf/internal/consts/consts_gen_ctrl_template_sdk.go

@@ -81,7 +81,7 @@ func (i *implementer) {ImplementerName}() {Module}.I{ImplementerName} {
 
 `
 
-const TemplateGenCtrlSdkImplementerFunc = `
+const TemplateGenCtrlSdkImplementerFunc = `{MethodComment}
 func (i *implementer{ImplementerName}) {MethodName}(ctx context.Context, req *{Version}.{MethodName}Req) (res *{Version}.{MethodName}Res, err error) {
 	err = i.Request(ctx, req, &res)
 	return