Linting 🅰️

Former-commit-id: 367bb53ed6656002c60c40e3ad30bda578de21c6

core/router/macro/macro.go

@@ -13,9 +13,16 @@ import (
 	"github.com/kataras/iris/core/router/macro/interpreter/ast"
 )
 
-// final evaluator signature for both param types and param funcs
+// EvaluatorFunc is the signature for both param types and param funcs.
+// It should accepts the param's value as string
+// and return true if validated otherwise false.
 type EvaluatorFunc func(paramValue string) bool
 
+// NewEvaluatorFromRegexp accepts a regexp "expr" expression
+// and returns an EvaluatorFunc based on that regexp.
+// the regexp is compiled before return.
+//
+// Returns a not-nil error on regexp compile failure.
 func NewEvaluatorFromRegexp(expr string) (EvaluatorFunc, error) {
 	if expr == "" {
 		return nil, fmt.Errorf("empty regex expression")
@@ -34,6 +41,8 @@ func NewEvaluatorFromRegexp(expr string) (EvaluatorFunc, error) {
 	return r.MatchString, nil
 }
 
+// MustNewEvaluatorFromRegexp same as NewEvaluatorFromRegexp
+// but it panics on the "expr" parse failure.
 func MustNewEvaluatorFromRegexp(expr string) EvaluatorFunc {
 	r, err := NewEvaluatorFromRegexp(expr)
 	if err != nil {
@@ -122,13 +131,34 @@ func convertBuilderFunc(fn interface{}) ParamEvaluatorBuilder {
 }
 
 type (
+	// Macro represents the parsed macro,
+	// which holds
+	// the evaluator (param type's evaluator + param functions evaluators)
+	// and its param functions.
+	//
+	// Any type contains its own macro
+	// instance, so an String type
+	// contains its type evaluator
+	// which is the "Evaluator" field
+	// and it can register param functions
+	// to that macro which maps to a parameter type.
 	Macro struct {
 		Evaluator EvaluatorFunc
 		funcs     []ParamFunc
 	}
 
+	// ParamEvaluatorBuilder is a func
+	// which accepts a param function's arguments (values)
+	// and returns an EvaluatorFunc, its job
+	// is to make the macros to be registered
+	// by user at the most generic possible way.
 	ParamEvaluatorBuilder func([]ast.ParamFuncArg) EvaluatorFunc
 
+	// ParamFunc represents the parsed
+	// parameter function, it holds
+	// the parameter's name
+	// and the function which will build
+	// the evaluator func.
 	ParamFunc struct {
 		Name string
 		Func ParamEvaluatorBuilder
@@ -139,7 +169,12 @@ func newMacro(evaluator EvaluatorFunc) *Macro {
 	return &Macro{Evaluator: evaluator}
 }
 
-// at boot time, per param
+// RegisterFunc registers a parameter function
+// to that macro.
+// Accepts the func name ("range")
+// and the function body, which should return an EvaluatorFunc
+// a bool (it will be converted to EvaluatorFunc later on),
+// i.e RegisterFunc("min", func(minValue int) func(paramValue string) bool){})
 func (m *Macro) RegisterFunc(funcName string, fn interface{}) {
 	fullFn := convertBuilderFunc(fn)
 	m.registerFunc(funcName, fullFn)
@@ -175,7 +210,10 @@ func (m *Macro) getFunc(funcName string) ParamEvaluatorBuilder {
 	return nil
 }
 
-type MacroMap struct {
+// Map contains the default macros mapped to their types.
+// This is the manager which is used by the caller to register custom
+// parameter functions per param-type (String, Int, Alphabetical, File, Path).
+type Map struct {
 	// string type
 	// anything
 	String *Macro
@@ -198,8 +236,12 @@ type MacroMap struct {
 	Path *Macro
 }
 
-func NewMacroMap() *MacroMap {
-	return &MacroMap{
+// NewMap returns a new macro Map with default
+// type evaluators.
+//
+// Learn more at:  https://github.com/kataras/iris/tree/master/_examples/beginner/routing/dynamic-path
+func NewMap() *Map {
+	return &Map{
 		// it allows everything, so no need for a regexp here.
 		String:       newMacro(func(string) bool { return true }),
 		Int:          newMacro(MustNewEvaluatorFromRegexp("^[0-9]+$")),
@@ -213,7 +255,11 @@ func NewMacroMap() *MacroMap {
 	}
 }
 
-func (m *MacroMap) Lookup(typ ast.ParamType) *Macro {
+// Lookup returns the specific Macro from the map
+// based on the parameter type.
+// i.e if ast.ParamTypeInt then it will return the m.Int.
+// Returns the m.String if not matched.
+func (m *Map) Lookup(typ ast.ParamType) *Macro {
 	switch typ {
 	case ast.ParamTypeInt:
 		return m.Int