Code optimized (#523)

* optimized markdown generator

* optimized markdown generator

* optimized markdown generator

* add more comment

* add comment

* add comment

* add comments for rpc tool

* add comments for model tool

* add comments for model tool

* add comments for model tool

* add comments for config tool

* add comments for config tool

* add comments

* add comments

* add comments

* add comments

* add comment

* remove rpc main head info

* add comment

* optimized

Co-authored-by: anqiansong <anqiansong@xiaoheiban.cn>

tools/goctl/rpc/generator/defaultgenerator.go

@@ -6,18 +6,22 @@ import (
 	"github.com/tal-tech/go-zero/tools/goctl/util/console"
 )
 
-type defaultGenerator struct {
+// DefaultGenerator defines the environment needs of rpc service generation
+type DefaultGenerator struct {
 	log console.Console
 }
 
-func NewDefaultGenerator() *defaultGenerator {
+// NewDefaultGenerator returns an instance of DefaultGenerator
+func NewDefaultGenerator() *DefaultGenerator {
 	log := console.NewColorConsole()
-	return &defaultGenerator{
+	return &DefaultGenerator{
 		log: log,
 	}
 }
 
-func (g *defaultGenerator) Prepare() error {
+// Prepare provides environment detection generated by rpc service,
+// including go environment, protoc, whether protoc-gen-go is installed or not
+func (g *DefaultGenerator) Prepare() error {
 	_, err := exec.LookPath("go")
 	if err != nil {
 		return err

tools/goctl/rpc/generator/gen.go

@@ -10,27 +10,33 @@ import (
 	"github.com/tal-tech/go-zero/tools/goctl/util/ctx"
 )
 
-type RpcGenerator struct {
+// RPCGenerator defines a generator and configure
+type RPCGenerator struct {
 	g   Generator
 	cfg *conf.Config
 }
 
-func NewDefaultRpcGenerator(style string) (*RpcGenerator, error) {
+// NewDefaultRPCGenerator wraps Generator with configure
+func NewDefaultRPCGenerator(style string) (*RPCGenerator, error) {
 	cfg, err := conf.NewConfig(style)
 	if err != nil {
 		return nil, err
 	}
-	return NewRpcGenerator(NewDefaultGenerator(), cfg), nil
+	return NewRPCGenerator(NewDefaultGenerator(), cfg), nil
 }
 
-func NewRpcGenerator(g Generator, cfg *conf.Config) *RpcGenerator {
-	return &RpcGenerator{
+// NewRPCGenerator creates an instance for RPCGenerator
+func NewRPCGenerator(g Generator, cfg *conf.Config) *RPCGenerator {
+	return &RPCGenerator{
 		g:   g,
 		cfg: cfg,
 	}
 }
 
-func (g *RpcGenerator) Generate(src, target string, protoImportPath []string) error {
+// Generate generates an rpc service, through the proto file,
+// code storage directory, and proto import parameters to control
+// the source file and target location of the rpc service that needs to be generated
+func (g *RPCGenerator) Generate(src, target string, protoImportPath []string) error {
 	abs, err := filepath.Abs(target)
 	if err != nil {
 		return err

tools/goctl/rpc/generator/gen_test.go

@@ -27,7 +27,7 @@ func TestRpcGenerate(t *testing.T) {
 		return
 	}
 	projectName := stringx.Rand()
-	g := NewRpcGenerator(dispatcher, cfg)
+	g := NewRPCGenerator(dispatcher, cfg)
 
 	// case go path
 	src := filepath.Join(build.Default.GOPATH, "src")

tools/goctl/rpc/generator/gencall.go

@@ -61,7 +61,9 @@ func (m *default{{.serviceName}}) {{.method}}(ctx context.Context,in *{{.pbReque
 `
 )
 
-func (g *defaultGenerator) GenCall(ctx DirContext, proto parser.Proto, cfg *conf.Config) error {
+// GenCall generates the rpc client code, which is the entry point for the rpc service call.
+// It is a layer of encapsulation for the rpc client and shields the details in the pb.
+func (g *DefaultGenerator) GenCall(ctx DirContext, proto parser.Proto, cfg *conf.Config) error {
 	dir := ctx.GetCall()
 	service := proto.Service
 	head := util.GetHead(proto.Name)
@@ -105,7 +107,7 @@ func (g *defaultGenerator) GenCall(ctx DirContext, proto parser.Proto, cfg *conf
 	return err
 }
 
-func (g *defaultGenerator) genFunction(goPackage string, service parser.Service) ([]string, error) {
+func (g *DefaultGenerator) genFunction(goPackage string, service parser.Service) ([]string, error) {
 	functions := make([]string, 0)
 	for _, rpc := range service.RPC {
 		text, err := util.LoadTemplate(category, callFunctionTemplateFile, callFunctionTemplate)
@@ -133,7 +135,7 @@ func (g *defaultGenerator) genFunction(goPackage string, service parser.Service)
 	return functions, nil
 }
 
-func (g *defaultGenerator) getInterfaceFuncs(service parser.Service) ([]string, error) {
+func (g *DefaultGenerator) getInterfaceFuncs(service parser.Service) ([]string, error) {
 	functions := make([]string, 0)
 
 	for _, rpc := range service.RPC {

tools/goctl/rpc/generator/genconfig.go

@@ -20,7 +20,11 @@ type Config struct {
 }
 `
 
-func (g *defaultGenerator) GenConfig(ctx DirContext, _ parser.Proto, cfg *conf.Config) error {
+// GenConfig generates the configuration structure definition file of the rpc service,
+// which contains the zrpc.RpcServerConf configuration item by default.
+// You can specify the naming style of the target file name through config.Config. For details,
+// see https://github.com/tal-tech/go-zero/tree/master/tools/goctl/config/config.go
+func (g *DefaultGenerator) GenConfig(ctx DirContext, _ parser.Proto, cfg *conf.Config) error {
 	dir := ctx.GetConfig()
 	configFilename, err := format.FileNamingFormat(cfg.NamingFormat, "config")
 	if err != nil {

tools/goctl/rpc/generator/generator.go

@@ -5,6 +5,7 @@ import (
 	"github.com/tal-tech/go-zero/tools/goctl/rpc/parser"
 )
 
+// Generator defines a generator interface to describe how to generate rpc service
 type Generator interface {
 	Prepare() error
 	GenMain(ctx DirContext, proto parser.Proto, cfg *conf.Config) error

tools/goctl/rpc/generator/genetc.go

@@ -20,7 +20,9 @@ Etcd:
   Key: {{.serviceName}}.rpc
 `
 
-func (g *defaultGenerator) GenEtc(ctx DirContext, _ parser.Proto, cfg *conf.Config) error {
+// GenEtc generates the yaml configuration file of the rpc service,
+// including host, port monitoring configuration items and etcd configuration
+func (g *DefaultGenerator) GenEtc(ctx DirContext, _ parser.Proto, cfg *conf.Config) error {
 	dir := ctx.GetEtc()
 	etcFilename, err := format.FileNamingFormat(cfg.NamingFormat, ctx.GetServiceName().Source())
 	if err != nil {

tools/goctl/rpc/generator/genlogic.go

@@ -48,7 +48,8 @@ func (l *{{.logicName}}) {{.method}} (in {{.request}}) ({{.response}}, error) {
 `
 )
 
-func (g *defaultGenerator) GenLogic(ctx DirContext, proto parser.Proto, cfg *conf.Config) error {
+// GenLogic generates the logic file of the rpc service, which corresponds to the RPC definition items in proto.
+func (g *DefaultGenerator) GenLogic(ctx DirContext, proto parser.Proto, cfg *conf.Config) error {
 	dir := ctx.GetLogic()
 	for _, rpc := range proto.Service.RPC {
 		logicFilename, err := format.FileNamingFormat(cfg.NamingFormat, rpc.Name+"_logic")
@@ -81,7 +82,7 @@ func (g *defaultGenerator) GenLogic(ctx DirContext, proto parser.Proto, cfg *con
 	return nil
 }
 
-func (g *defaultGenerator) genLogicFunction(goPackage string, rpc *parser.RPC) (string, error) {
+func (g *DefaultGenerator) genLogicFunction(goPackage string, rpc *parser.RPC) (string, error) {
 	var functions = make([]string, 0)
 	text, err := util.LoadTemplate(category, logicFuncTemplateFileFile, logicFunctionTemplate)
 	if err != nil {

tools/goctl/rpc/generator/genmain.go

@@ -12,9 +12,7 @@ import (
 	"github.com/tal-tech/go-zero/tools/goctl/util/stringx"
 )
 
-const mainTemplate = `{{.head}}
-
-package main
+const mainTemplate = `package main
 
 import (
 	"flag"
@@ -47,7 +45,8 @@ func main() {
 }
 `
 
-func (g *defaultGenerator) GenMain(ctx DirContext, proto parser.Proto, cfg *conf.Config) error {
+// GenMain generates the main file of the rpc service, which is an rpc service program call entry
+func (g *DefaultGenerator) GenMain(ctx DirContext, proto parser.Proto, cfg *conf.Config) error {
 	mainFilename, err := format.FileNamingFormat(cfg.NamingFormat, ctx.GetServiceName().Source())
 	if err != nil {
 		return err
@@ -60,14 +59,12 @@ func (g *defaultGenerator) GenMain(ctx DirContext, proto parser.Proto, cfg *conf
 	remoteImport := fmt.Sprintf(`"%v"`, ctx.GetServer().Package)
 	configImport := fmt.Sprintf(`"%v"`, ctx.GetConfig().Package)
 	imports = append(imports, configImport, pbImport, remoteImport, svcImport)
-	head := util.GetHead(proto.Name)
 	text, err := util.LoadTemplate(category, mainTemplateFile, mainTemplate)
 	if err != nil {
 		return err
 	}
 
 	return util.With("main").GoFmt(true).Parse(text).SaveTo(map[string]interface{}{
-		"head":        head,
 		"serviceName": strings.ToLower(ctx.GetServiceName().ToCamel()),
 		"imports":     strings.Join(imports, util.NL),
 		"pkg":         proto.PbPackage,

tools/goctl/rpc/generator/genpb.go

@@ -10,7 +10,9 @@ import (
 	"github.com/tal-tech/go-zero/tools/goctl/rpc/parser"
 )
 
-func (g *defaultGenerator) GenPb(ctx DirContext, protoImportPath []string, proto parser.Proto, _ *conf.Config) error {
+// GenPb generates the pb.go file, which is a layer of packaging for protoc to generate gprc,
+// but the commands and flags in protoc are not completely joined in goctl. At present, proto_path(-I) is introduced
+func (g *DefaultGenerator) GenPb(ctx DirContext, protoImportPath []string, proto parser.Proto, _ *conf.Config) error {
 	dir := ctx.GetPb()
 	cw := new(bytes.Buffer)
 	base := filepath.Dir(proto.Src)

tools/goctl/rpc/generator/genserver.go

@@ -45,7 +45,8 @@ func (s *{{.server}}Server) {{.method}} (ctx context.Context, in {{.request}}) (
 `
 )
 
-func (g *defaultGenerator) GenServer(ctx DirContext, proto parser.Proto, cfg *conf.Config) error {
+// GenServer generates rpc server file, which is an implementation of rpc server
+func (g *DefaultGenerator) GenServer(ctx DirContext, proto parser.Proto, cfg *conf.Config) error {
 	dir := ctx.GetServer()
 	logicImport := fmt.Sprintf(`"%v"`, ctx.GetLogic().Package)
 	svcImport := fmt.Sprintf(`"%v"`, ctx.GetSvc().Package)
@@ -81,7 +82,7 @@ func (g *defaultGenerator) GenServer(ctx DirContext, proto parser.Proto, cfg *co
 	return err
 }
 
-func (g *defaultGenerator) genFunctions(goPackage string, service parser.Service) ([]string, error) {
+func (g *DefaultGenerator) genFunctions(goPackage string, service parser.Service) ([]string, error) {
 	var functionList []string
 	for _, rpc := range service.RPC {
 		text, err := util.LoadTemplate(category, serverFuncTemplateFile, functionTemplate)

tools/goctl/rpc/generator/gensvc.go

@@ -25,7 +25,9 @@ func NewServiceContext(c config.Config) *ServiceContext {
 }
 `
 
-func (g *defaultGenerator) GenSvc(ctx DirContext, _ parser.Proto, cfg *conf.Config) error {
+// GenSvc generates the servicecontext.go file, which is the resource dependency of a service,
+// such as rpc dependency, model dependency, etc.
+func (g *DefaultGenerator) GenSvc(ctx DirContext, _ parser.Proto, cfg *conf.Config) error {
 	dir := ctx.GetSvc()
 	svcFilename, err := format.FileNamingFormat(cfg.NamingFormat, "service_context")
 	if err != nil {

tools/goctl/rpc/generator/mkdir.go

@@ -23,6 +23,7 @@ const (
 )
 
 type (
+	// DirContext defines a rpc service directories context
 	DirContext interface {
 		GetCall() Dir
 		GetEtc() Dir
@@ -36,11 +37,13 @@ type (
 		GetServiceName() stringx.String
 	}
 
+	// Dir defines a directory
 	Dir struct {
 		Base     string
 		Filename string
 		Package  string
 	}
+
 	defaultDirContext struct {
 		inner       map[string]Dir
 		serviceName stringx.String
@@ -159,6 +162,7 @@ func (d *defaultDirContext) GetServiceName() stringx.String {
 	return d.serviceName
 }
 
+// Valid returns true if the directory is valid
 func (d *Dir) Valid() bool {
 	return len(d.Filename) > 0 && len(d.Package) > 0
 }

tools/goctl/rpc/generator/prototmpl.go

@@ -25,6 +25,7 @@ service {{.serviceName}} {
 }
 `
 
+// ProtoTmpl returns an sample of a proto file
 func ProtoTmpl(out string) error {
 	protoFilename := filepath.Base(out)
 	serviceName := stringx.From(strings.TrimSuffix(protoFilename, filepath.Ext(protoFilename)))

tools/goctl/rpc/generator/template.go

@@ -38,10 +38,13 @@ var templates = map[string]string{
 	rpcTemplateFile:                   rpcTemplateText,
 }
 
+// GenTemplates is the entry for command goctl template,
+// it will create the specified category
 func GenTemplates(_ *cli.Context) error {
 	return util.InitTemplates(category, templates)
 }
 
+// RevertTemplate restores the deleted template files
 func RevertTemplate(name string) error {
 	content, ok := templates[name]
 	if !ok {
@@ -50,10 +53,13 @@ func RevertTemplate(name string) error {
 	return util.CreateTemplate(category, name, content)
 }
 
+// Clean deletes all template files
 func Clean() error {
 	return util.Clean(category)
 }
 
+// Update is used to update the template files, it will delete the existing old templates at first,
+// and then create the latest template files
 func Update() error {
 	err := Clean()
 	if err != nil {
@@ -63,6 +69,7 @@ func Update() error {
 	return util.InitTemplates(category, templates)
 }
 
+// Category returns a const string value for rpc template category
 func Category() string {
 	return category
 }