Skip to content

Commit

Permalink
tpl: Improve godoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@bep
bep committed May 6, 2022
1 parent a6d5458 commit 6eea32b
Show file tree
Hide file tree
Showing 8 changed files with 142 additions and 141 deletions.
6 changes: 3 additions & 3 deletions tpl/cast/cast.go
View file
Expand Up @@ -29,18 +29,18 @@ func New() *Namespace {
type Namespace struct {
}

// ToInt converts the given value to an int.
// ToInt converts v to an int.
func (ns *Namespace) ToInt(v any) (int, error) {
v = convertTemplateToString(v)
return _cast.ToIntE(v)
}

// ToString converts the given value to a string.
// ToString converts v to a string.
func (ns *Namespace) ToString(v any) (string, error) {
return _cast.ToStringE(v)
}

// ToFloat converts the given value to a float.
// ToFloat converts v to a float.
func (ns *Namespace) ToFloat(v any) (float64, error) {
v = convertTemplateToString(v)
return _cast.ToFloat64E(v)
Expand Down
36 changes: 18 additions & 18 deletions tpl/fmt/fmt.go
View file
Expand Up @@ -47,39 +47,39 @@ type Namespace struct {
distinctLogger loggers.IgnorableLogger
}

// Print returns string representation of the passed arguments.
func (ns *Namespace) Print(a ...any) string {
return _fmt.Sprint(a...)
// Print returns a string representation args.
func (ns *Namespace) Print(args ...any) string {
return _fmt.Sprint(args...)
}

// Printf returns a formatted string representation of the passed arguments.
func (ns *Namespace) Printf(format string, a ...any) string {
return _fmt.Sprintf(format, a...)
// Printf returns a formatted string representation of args.
func (ns *Namespace) Printf(format string, args ...any) string {
return _fmt.Sprintf(format, args...)
}

// Println returns string representation of the passed arguments ending with a newline.
func (ns *Namespace) Println(a ...any) string {
return _fmt.Sprintln(a...)
// Println returns string representation of args ending with a newline.
func (ns *Namespace) Println(args ...any) string {
return _fmt.Sprintln(args...)
}

// Errorf formats according to a format specifier and logs an ERROR.
// Errorf formats args according to a format specifier and logs an ERROR.
// It returns an empty string.
func (ns *Namespace) Errorf(format string, a ...any) string {
ns.distinctLogger.Errorf(format, a...)
func (ns *Namespace) Errorf(format string, args ...any) string {
ns.distinctLogger.Errorf(format, args...)
return ""
}

// Erroridf formats according to a format specifier and logs an ERROR and
// Erroridf formats args according to a format specifier and logs an ERROR and
// an information text that the error with the given ID can be suppressed in config.
// It returns an empty string.
func (ns *Namespace) Erroridf(id, format string, a ...any) string {
ns.distinctLogger.Errorsf(id, format, a...)
func (ns *Namespace) Erroridf(id, format string, args ...any) string {
ns.distinctLogger.Errorsf(id, format, args...)
return ""
}

// Warnf formats according to a format specifier and logs a WARNING.
// Warnf formats args according to a format specifier and logs a WARNING.
// It returns an empty string.
func (ns *Namespace) Warnf(format string, a ...any) string {
ns.distinctLogger.Warnf(format, a...)
func (ns *Namespace) Warnf(format string, args ...any) string {
ns.distinctLogger.Warnf(format, args...)
return ""
}
92 changes: 46 additions & 46 deletions tpl/math/math.go
View file
Expand Up @@ -32,50 +32,50 @@ func New() *Namespace {
// Namespace provides template functions for the "math" namespace.
type Namespace struct{}

// Add adds two numbers.
func (ns *Namespace) Add(a, b any) (any, error) {
return _math.DoArithmetic(a, b, '+')
// Add adds the two addends n1 and n2.
func (ns *Namespace) Add(n1, n2 any) (any, error) {
return _math.DoArithmetic(n1, n2, '+')
}

// Ceil returns the least integer value greater than or equal to x.
func (ns *Namespace) Ceil(x any) (float64, error) {
xf, err := cast.ToFloat64E(x)
// Ceil returns the least integer value greater than or equal to n.
func (ns *Namespace) Ceil(n any) (float64, error) {
xf, err := cast.ToFloat64E(n)
if err != nil {
return 0, errors.New("Ceil operator can't be used with non-float value")
}

return math.Ceil(xf), nil
}

// Div divides two numbers.
func (ns *Namespace) Div(a, b any) (any, error) {
return _math.DoArithmetic(a, b, '/')
// Div divides n1 by n2.
func (ns *Namespace) Div(n1, n2 any) (any, error) {
return _math.DoArithmetic(n1, n2, '/')
}

// Floor returns the greatest integer value less than or equal to x.
func (ns *Namespace) Floor(x any) (float64, error) {
xf, err := cast.ToFloat64E(x)
// Floor returns the greatest integer value less than or equal to n.
func (ns *Namespace) Floor(n any) (float64, error) {
xf, err := cast.ToFloat64E(n)
if err != nil {
return 0, errors.New("Floor operator can't be used with non-float value")
}

return math.Floor(xf), nil
}

// Log returns the natural logarithm of a number.
func (ns *Namespace) Log(a any) (float64, error) {
af, err := cast.ToFloat64E(a)
// Log returns the natural logarithm of the number n.
func (ns *Namespace) Log(n any) (float64, error) {
af, err := cast.ToFloat64E(n)
if err != nil {
return 0, errors.New("Log operator can't be used with non integer or float value")
}

return math.Log(af), nil
}

// Max returns the greater of two numbers.
func (ns *Namespace) Max(a, b any) (float64, error) {
af, erra := cast.ToFloat64E(a)
bf, errb := cast.ToFloat64E(b)
// Max returns the greater of the two numbers n1 or n2.
func (ns *Namespace) Max(n1, n2 any) (float64, error) {
af, erra := cast.ToFloat64E(n1)
bf, errb := cast.ToFloat64E(n2)

if erra != nil || errb != nil {
return 0, errors.New("Max operator can't be used with non-float value")
Expand All @@ -84,10 +84,10 @@ func (ns *Namespace) Max(a, b any) (float64, error) {
return math.Max(af, bf), nil
}

// Min returns the smaller of two numbers.
func (ns *Namespace) Min(a, b any) (float64, error) {
af, erra := cast.ToFloat64E(a)
bf, errb := cast.ToFloat64E(b)
// Min returns the smaller of two numbers n1 or n2.
func (ns *Namespace) Min(n1, n2 any) (float64, error) {
af, erra := cast.ToFloat64E(n1)
bf, errb := cast.ToFloat64E(n2)

if erra != nil || errb != nil {
return 0, errors.New("Min operator can't be used with non-float value")
Expand All @@ -96,10 +96,10 @@ func (ns *Namespace) Min(a, b any) (float64, error) {
return math.Min(af, bf), nil
}

// Mod returns a % b.
func (ns *Namespace) Mod(a, b any) (int64, error) {
ai, erra := cast.ToInt64E(a)
bi, errb := cast.ToInt64E(b)
// Mod returns n1 % n2.
func (ns *Namespace) Mod(n1, n2 any) (int64, error) {
ai, erra := cast.ToInt64E(n1)
bi, errb := cast.ToInt64E(n2)

if erra != nil || errb != nil {
return 0, errors.New("modulo operator can't be used with non integer value")
Expand All @@ -112,25 +112,25 @@ func (ns *Namespace) Mod(a, b any) (int64, error) {
return ai % bi, nil
}

// ModBool returns the boolean of a % b. If a % b == 0, return true.
func (ns *Namespace) ModBool(a, b any) (bool, error) {
res, err := ns.Mod(a, b)
// ModBool returns the boolean of n1 % n2. If n1 % n2 == 0, return true.
func (ns *Namespace) ModBool(n1, n2 any) (bool, error) {
res, err := ns.Mod(n1, n2)
if err != nil {
return false, err
}

return res == int64(0), nil
}

// Mul multiplies two numbers.
func (ns *Namespace) Mul(a, b any) (any, error) {
return _math.DoArithmetic(a, b, '*')
// Mul multiplies the two numbers n1 and n2.
func (ns *Namespace) Mul(n1, n2 any) (any, error) {
return _math.DoArithmetic(n1, n2, '*')
}

// Pow returns a raised to the power of b.
func (ns *Namespace) Pow(a, b any) (float64, error) {
af, erra := cast.ToFloat64E(a)
bf, errb := cast.ToFloat64E(b)
// Pow returns n1 raised to the power of n2.
func (ns *Namespace) Pow(n1, n2 any) (float64, error) {
af, erra := cast.ToFloat64E(n1)
bf, errb := cast.ToFloat64E(n2)

if erra != nil || errb != nil {
return 0, errors.New("Pow operator can't be used with non-float value")
Expand All @@ -139,29 +139,29 @@ func (ns *Namespace) Pow(a, b any) (float64, error) {
return math.Pow(af, bf), nil
}

// Round returns the nearest integer, rounding half away from zero.
func (ns *Namespace) Round(x any) (float64, error) {
xf, err := cast.ToFloat64E(x)
// Round returns the integer nearest to n, rounding half away from zero.
func (ns *Namespace) Round(n any) (float64, error) {
xf, err := cast.ToFloat64E(n)
if err != nil {
return 0, errors.New("Round operator can't be used with non-float value")
}

return _round(xf), nil
}

// Sqrt returns the square root of a number.
func (ns *Namespace) Sqrt(a any) (float64, error) {
af, err := cast.ToFloat64E(a)
// Sqrt returns the square root of the number n.
func (ns *Namespace) Sqrt(n any) (float64, error) {
af, err := cast.ToFloat64E(n)
if err != nil {
return 0, errors.New("Sqrt operator can't be used with non integer or float value")
}

return math.Sqrt(af), nil
}

// Sub subtracts two numbers.
func (ns *Namespace) Sub(a, b any) (any, error) {
return _math.DoArithmetic(a, b, '-')
// Sub subtracts n2 from n1.
func (ns *Namespace) Sub(n1, n2 any) (any, error) {
return _math.DoArithmetic(n1, n2, '-')
}

var counter uint64
Expand Down
52 changes: 26 additions & 26 deletions tpl/safe/safe.go
View file
Expand Up @@ -30,44 +30,44 @@ func New() *Namespace {
// Namespace provides template functions for the "safe" namespace.
type Namespace struct{}

// CSS returns a given string as html/template CSS content.
func (ns *Namespace) CSS(a any) (template.CSS, error) {
s, err := cast.ToStringE(a)
return template.CSS(s), err
// CSS returns the string s as html/template CSS content.
func (ns *Namespace) CSS(s any) (template.CSS, error) {
ss, err := cast.ToStringE(s)
return template.CSS(ss), err
}

// HTML returns a given string as html/template HTML content.
func (ns *Namespace) HTML(a any) (template.HTML, error) {
s, err := cast.ToStringE(a)
return template.HTML(s), err
// HTML returns the string s as html/template HTML content.
func (ns *Namespace) HTML(s any) (template.HTML, error) {
ss, err := cast.ToStringE(s)
return template.HTML(ss), err
}

// HTMLAttr returns a given string as html/template HTMLAttr content.
func (ns *Namespace) HTMLAttr(a any) (template.HTMLAttr, error) {
s, err := cast.ToStringE(a)
return template.HTMLAttr(s), err
// HTMLAttr returns the string s as html/template HTMLAttr content.
func (ns *Namespace) HTMLAttr(s any) (template.HTMLAttr, error) {
ss, err := cast.ToStringE(s)
return template.HTMLAttr(ss), err
}

// JS returns the given string as a html/template JS content.
func (ns *Namespace) JS(a any) (template.JS, error) {
s, err := cast.ToStringE(a)
return template.JS(s), err
func (ns *Namespace) JS(s any) (template.JS, error) {
ss, err := cast.ToStringE(s)
return template.JS(ss), err
}

// JSStr returns the given string as a html/template JSStr content.
func (ns *Namespace) JSStr(a any) (template.JSStr, error) {
s, err := cast.ToStringE(a)
return template.JSStr(s), err
func (ns *Namespace) JSStr(s any) (template.JSStr, error) {
ss, err := cast.ToStringE(s)
return template.JSStr(ss), err
}

// URL returns a given string as html/template URL content.
func (ns *Namespace) URL(a any) (template.URL, error) {
s, err := cast.ToStringE(a)
return template.URL(s), err
// URL returns the string s as html/template URL content.
func (ns *Namespace) URL(s any) (template.URL, error) {
ss, err := cast.ToStringE(s)
return template.URL(ss), err
}

// SanitizeURL returns a given string as html/template URL content.
func (ns *Namespace) SanitizeURL(a any) (string, error) {
s, err := cast.ToStringE(a)
return helpers.SanitizeURL(s), err
// SanitizeURL returns the string s as html/template URL content.
func (ns *Namespace) SanitizeURL(s any) (string, error) {
ss, err := cast.ToStringE(s)
return helpers.SanitizeURL(ss), err
}
8 changes: 4 additions & 4 deletions tpl/strings/strings.go
View file
Expand Up @@ -372,7 +372,7 @@ func (ns *Namespace) Title(s any) (string, error) {
return ns.titleFunc(ss), nil
}

// FirstUpper returns a string with the first character as upper case.
// FirstUpper converts s making the first character upper case.
func (ns *Namespace) FirstUpper(s any) (string, error) {
ss, err := cast.ToStringE(s)
if err != nil {
Expand Down Expand Up @@ -404,8 +404,8 @@ func (ns *Namespace) ToUpper(s any) (string, error) {
return strings.ToUpper(ss), nil
}

// Trim returns a string with all leading and trailing characters defined
// contained in cutset removed.
// Trim returns converts the strings s removing all leading and trailing characters defined
// contained.
func (ns *Namespace) Trim(s, cutset any) (string, error) {
ss, err := cast.ToStringE(s)
if err != nil {
Expand Down Expand Up @@ -484,7 +484,7 @@ func (ns *Namespace) TrimSuffix(suffix, s any) (string, error) {
return strings.TrimSuffix(ss, sx), nil
}

// Repeat returns a new string consisting of count copies of the string s.
// Repeat returns a new string consisting of n copies of the string s.
func (ns *Namespace) Repeat(n, s any) (string, error) {
ss, err := cast.ToStringE(s)
if err != nil {
Expand Down
13 changes: 6 additions & 7 deletions tpl/time/time.go
View file
Expand Up @@ -57,9 +57,8 @@ func (ns *Namespace) AsTime(v any, args ...any) (any, error) {

}

// Format converts the textual representation of the datetime string into
// the other form or returns it of the time.Time value. These are formatted
// with the layout string
// Format converts the textual representation of the datetime string in v into
// time.Time if needed and formats it with the given layout.
func (ns *Namespace) Format(layout string, v any) (string, error) {
t, err := htime.ToTimeInDefaultLocationE(v, ns.location)
if err != nil {
Expand All @@ -74,19 +73,19 @@ func (ns *Namespace) Now() _time.Time {
return _time.Now()
}

// ParseDuration parses a duration string.
// ParseDuration parses the duration string s.
// A duration string is a possibly signed sequence of
// decimal numbers, each with optional fraction and a unit suffix,
// such as "300ms", "-1.5h" or "2h45m".
// Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
// See https://golang.org/pkg/time/#ParseDuration
func (ns *Namespace) ParseDuration(in any) (_time.Duration, error) {
s, err := cast.ToStringE(in)
func (ns *Namespace) ParseDuration(s any) (_time.Duration, error) {
ss, err := cast.ToStringE(s)
if err != nil {
return 0, err
}

return _time.ParseDuration(s)
return _time.ParseDuration(ss)
}

var durationUnits = map[string]_time.Duration{
Expand Down

0 comments on commit 6eea32b

Please sign in to comment.