Linting 🅰️

Former-commit-id: 367bb53ed6656002c60c40e3ad30bda578de21c6

core/router/macro/interpreter/ast/ast.go

@@ -9,19 +9,39 @@ import (
 	"strconv"
 )
 
+// ParamType is a specific uint8 type
+// which holds the parameter types' type.
 type ParamType uint8
 
 const (
+	// ParamTypeUnExpected is an unexpected parameter type.
 	ParamTypeUnExpected ParamType = iota
-	// /myparam1
+	// ParamTypeString 	is the string type.
+	// If parameter type is missing then it defaults to String type.
+	// Allows anything
+	// Declaration: /mypath/{myparam:string} or /mypath{myparam}
 	ParamTypeString
-	// /42
+	// ParamTypeInt is the integer, a number type.
+	// Allows only numbers (0-9)
+	// Declaration: /mypath/{myparam:int}
 	ParamTypeInt
-	// /myparam
+	// ParamTypeAlphabetical is the  alphabetical/letter type type.
+	// Allows letters only (upper or lowercase)
+	// Declaration:  /mypath/{myparam:alphabetical}
 	ParamTypeAlphabetical
-	// /main.css
+	// ParamTypeFile  is the file single path type.
+	// Allows:
+	// letters (upper or lowercase)
+	// numbers (0-9)
+	// underscore (_)
+	// dash (-)
+	// point (.)
+	// no spaces! or other character
+	// Declaration: /mypath/{myparam:file}
 	ParamTypeFile
-	// /myparam1/myparam2
+	// ParamTypePath is the multi path (or wildcard) type.
+	// Allows anything, should be the last part
+	// Declaration: /mypath/{myparam:path}
 	ParamTypePath
 )
 
@@ -38,6 +58,14 @@ var paramTypes = map[string]ParamType{
 
 }
 
+// LookupParamType accepts the string
+// representation of a parameter type.
+// Available:
+// "string"
+// "int"
+// "alphabetical"
+// "file"
+// "path"
 func LookupParamType(ident string) ParamType {
 	if typ, ok := paramTypes[ident]; ok {
 		return typ
@@ -45,6 +73,14 @@ func LookupParamType(ident string) ParamType {
 	return ParamTypeUnExpected
 }
 
+// ParamStatement is a struct
+// which holds all the necessary information about a macro parameter.
+// It holds its type (string, int, alphabetical, file, path),
+// its source ({param:type}),
+// its name ("param"),
+// its attached functions by the user (min, max...)
+// and the http error code if that parameter
+// failed to be evaluated.
 type ParamStatement struct {
 	Src       string      // the original unparsed source, i.e: {id:int range(1,5) else 404}
 	Name      string      // id
@@ -53,35 +89,11 @@ type ParamStatement struct {
 	ErrorCode int         // 404
 }
 
+// ParamFuncArg represents a single parameter function's argument
 type ParamFuncArg interface{}
 
-func ParamFuncArgInt64(a ParamFuncArg) (int64, bool) {
-	if v, ok := a.(int64); ok {
-		return v, false
-	}
-	return -1, false
-}
-
-func ParamFuncArgToInt64(a ParamFuncArg) (int64, error) {
-	switch a.(type) {
-	case int64:
-		return a.(int64), nil
-	case string:
-		return strconv.ParseInt(a.(string), 10, 64)
-	case int:
-		return int64(a.(int)), nil
-	default:
-		return -1, fmt.Errorf("unexpected function argument type: %q", a)
-	}
-}
-
-func ParamFuncArgInt(a ParamFuncArg) (int, bool) {
-	if v, ok := a.(int); ok {
-		return v, false
-	}
-	return -1, false
-}
-
+// ParamFuncArgToInt converts and returns
+// any type of "a", to an integer.
 func ParamFuncArgToInt(a ParamFuncArg) (int, error) {
 	switch a.(type) {
 	case int:
@@ -95,26 +107,13 @@ func ParamFuncArgToInt(a ParamFuncArg) (int, error) {
 	}
 }
 
-func ParamFuncArgString(a ParamFuncArg) (string, bool) {
-	if v, ok := a.(string); ok {
-		return v, false
-	}
-	return "", false
-}
-
-func ParamFuncArgToString(a ParamFuncArg) (string, error) {
-	switch a.(type) {
-	case string:
-		return a.(string), nil
-	case int:
-		return strconv.Itoa(a.(int)), nil
-	case int64:
-		return strconv.FormatInt(a.(int64), 10), nil
-	default:
-		return "", fmt.Errorf("unexpected function argument type: %q", a)
-	}
-}
-
+// ParamFunc holds the name of a parameter's function
+// and its arguments (values)
+// A param func is declared with:
+// {param:int range(1,5)},
+// the range is the
+// param function name
+// the 1 and 5 are the two param function arguments
 // range(1,5)
 type ParamFunc struct {
 	Name string         // range

core/router/macro/interpreter/parser/parser.go

@@ -14,6 +14,9 @@ import (
 	"github.com/kataras/iris/core/router/macro/interpreter/token"
 )
 
+// Parse takes a route "fullpath"
+// and returns its param statements
+// and an error on failure.
 func Parse(fullpath string) ([]*ast.ParamStatement, error) {
 	pathParts := strings.SplitN(fullpath, "/", -1)
 	p := new(ParamParser)
@@ -45,20 +48,27 @@ func Parse(fullpath string) ([]*ast.ParamStatement, error) {
 	return statements, nil
 }
 
+// ParamParser is the parser
+// which is being used by the Parse function
+// to parse path segments one by one
+// and return their parsed parameter statements (param name, param type its functions and the inline route's functions).
 type ParamParser struct {
 	src    string
 	errors []string
 }
 
+// NewParamParser receives a "src" of a single parameter
+// and returns a new ParamParser, ready to Parse.
 func NewParamParser(src string) *ParamParser {
 	p := new(ParamParser)
 	p.Reset(src)
 	return p
 }
 
+// Reset resets this ParamParser,
+// reset the errors and set the source to the input "src".
 func (p *ParamParser) Reset(src string) {
 	p.src = src
-
 	p.errors = []string{}
 }
 
@@ -66,8 +76,15 @@ func (p *ParamParser) appendErr(format string, a ...interface{}) {
 	p.errors = append(p.errors, fmt.Sprintf(format, a...))
 }
 
-const DefaultParamErrorCode = 404
-const DefaultParamType = ast.ParamTypeString
+const (
+	// DefaultParamErrorCode is the default http error code, 404 not found,
+	// per-parameter. An error code can be setted via
+	// the "else" keyword inside a route's path.
+	DefaultParamErrorCode = 404
+	// DefaultParamType when parameter type is missing use this param type, defaults to string
+	// and it should be remains unless earth split in two.
+	DefaultParamType = ast.ParamTypeString
+)
 
 func parseParamFuncArg(t token.Token) (a ast.ParamFuncArg, err error) {
 	if t.Type == token.INT {
@@ -83,6 +100,8 @@ func (p ParamParser) Error() error {
 	return nil
 }
 
+// Parse parses the p.src and returns its param statement
+// and an error on failure.
 func (p *ParamParser) Parse() (*ast.ParamStatement, error) {
 	l := lexer.New(p.src)
 

core/router/macro/interpreter/parser/parser_test.go

@@ -129,7 +129,8 @@ func TestParseParam(t *testing.T) {
 			}}, // 7
 
 	}
-	var p *ParamParser = new(ParamParser)
+
+	p := new(ParamParser)
 	for i, tt := range tests {
 		p.Reset(tt.expectedStatement.Src)
 		resultStmt, err := p.Parse()