From 6eea32bd6bc8e7a7dd07a8cb6a8343ae2c74aba0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Sat, 30 Apr 2022 18:12:08 +0200 Subject: [PATCH] tpl: Improve godoc --- tpl/cast/cast.go | 6 +-- tpl/fmt/fmt.go | 36 +++++++-------- tpl/math/math.go | 92 +++++++++++++++++++------------------- tpl/safe/safe.go | 52 ++++++++++----------- tpl/strings/strings.go | 8 ++-- tpl/time/time.go | 13 +++--- tpl/transform/transform.go | 11 ++--- tpl/urls/urls.go | 65 ++++++++++++++------------- 8 files changed, 142 insertions(+), 141 deletions(-) diff --git a/tpl/cast/cast.go b/tpl/cast/cast.go index 000e315f1..535697f9e 100644 --- a/tpl/cast/cast.go +++ b/tpl/cast/cast.go @@ -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) diff --git a/tpl/fmt/fmt.go b/tpl/fmt/fmt.go index 3882d4704..7790b4955 100644 --- a/tpl/fmt/fmt.go +++ b/tpl/fmt/fmt.go @@ -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 "" } diff --git a/tpl/math/math.go b/tpl/math/math.go index fce44dc4b..257e803e4 100644 --- a/tpl/math/math.go +++ b/tpl/math/math.go @@ -32,14 +32,14 @@ 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") } @@ -47,14 +47,14 @@ func (ns *Namespace) Ceil(x any) (float64, error) { 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") } @@ -62,9 +62,9 @@ func (ns *Namespace) Floor(x any) (float64, error) { 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") } @@ -72,10 +72,10 @@ func (ns *Namespace) Log(a any) (float64, error) { 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") @@ -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") @@ -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") @@ -112,9 +112,9 @@ 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 } @@ -122,15 +122,15 @@ func (ns *Namespace) ModBool(a, b any) (bool, error) { 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") @@ -139,9 +139,9 @@ 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") } @@ -149,9 +149,9 @@ func (ns *Namespace) Round(x any) (float64, error) { 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") } @@ -159,9 +159,9 @@ func (ns *Namespace) Sqrt(a any) (float64, error) { 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 diff --git a/tpl/safe/safe.go b/tpl/safe/safe.go index 6c836b25c..d1a2e8d4e 100644 --- a/tpl/safe/safe.go +++ b/tpl/safe/safe.go @@ -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 } diff --git a/tpl/strings/strings.go b/tpl/strings/strings.go index af7c34a59..000490f85 100644 --- a/tpl/strings/strings.go +++ b/tpl/strings/strings.go @@ -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 { @@ -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 { @@ -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 { diff --git a/tpl/time/time.go b/tpl/time/time.go index f82d63c44..623b7206a 100644 --- a/tpl/time/time.go +++ b/tpl/time/time.go @@ -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 { @@ -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{ diff --git a/tpl/transform/transform.go b/tpl/transform/transform.go index 2f62557de..7c0914378 100644 --- a/tpl/transform/transform.go +++ b/tpl/transform/transform.go @@ -90,9 +90,9 @@ func (ns *Namespace) HighlightCodeBlock(ctx hooks.CodeblockContext, opts ...any) return hl.HighlightCodeBlock(ctx, optsv) } -// CanHighlight returns whether the given language is supported by the Chroma highlighter. -func (ns *Namespace) CanHighlight(lang string) bool { - return lexers.Get(lang) != nil +// CanHighlight returns whether the given code language is supported by the Chroma highlighter. +func (ns *Namespace) CanHighlight(language string) bool { + return lexers.Get(language) != nil } // HTMLEscape returns a copy of s with reserved HTML characters escaped. @@ -105,7 +105,7 @@ func (ns *Namespace) HTMLEscape(s any) (string, error) { return html.EscapeString(ss), nil } -// HTMLUnescape returns a copy of with HTML escape requences converted to plain +// HTMLUnescape returns a copy of s with HTML escape requences converted to plain // text. func (ns *Namespace) HTMLUnescape(s any) (string, error) { ss, err := cast.ToStringE(s) @@ -116,7 +116,7 @@ func (ns *Namespace) HTMLUnescape(s any) (string, error) { return html.UnescapeString(ss), nil } -// Markdownify renders a given input from Markdown to HTML. +// Markdownify renders s from Markdown to HTML. func (ns *Namespace) Markdownify(s any) (template.HTML, error) { home := ns.deps.Site.Home() @@ -144,6 +144,7 @@ func (ns *Namespace) Plainify(s any) (string, error) { return helpers.StripHTML(ss), nil } +// For internal use. func (ns *Namespace) Reset() { ns.cache.Clear() } diff --git a/tpl/urls/urls.go b/tpl/urls/urls.go index e07106261..3d6f67789 100644 --- a/tpl/urls/urls.go +++ b/tpl/urls/urls.go @@ -40,14 +40,14 @@ type Namespace struct { multihost bool } -// AbsURL takes a given string and converts it to an absolute URL. -func (ns *Namespace) AbsURL(a any) (template.HTML, error) { - s, err := cast.ToStringE(a) +// AbsURL takes the string s and converts it to an absolute URL. +func (ns *Namespace) AbsURL(s any) (template.HTML, error) { + ss, err := cast.ToStringE(s) if err != nil { return "", nil } - return template.HTML(ns.deps.PathSpec.AbsURL(s, false)), nil + return template.HTML(ns.deps.PathSpec.AbsURL(ss, false)), nil } // Parse parses rawurl into a URL structure. The rawurl may be relative or @@ -61,38 +61,39 @@ func (ns *Namespace) Parse(rawurl any) (*url.URL, error) { return url.Parse(s) } -// RelURL takes a given string and prepends the relative path according to a +// RelURL takes the string s and prepends the relative path according to a // page's position in the project directory structure. -func (ns *Namespace) RelURL(a any) (template.HTML, error) { - s, err := cast.ToStringE(a) +func (ns *Namespace) RelURL(s any) (template.HTML, error) { + ss, err := cast.ToStringE(s) if err != nil { return "", nil } - return template.HTML(ns.deps.PathSpec.RelURL(s, false)), nil + return template.HTML(ns.deps.PathSpec.RelURL(ss, false)), nil } -// URLize returns the given argument formatted as URL. -func (ns *Namespace) URLize(a any) (string, error) { - s, err := cast.ToStringE(a) +// URLize returns the the strings s formatted as an URL. +func (ns *Namespace) URLize(s any) (string, error) { + ss, err := cast.ToStringE(s) if err != nil { return "", nil } - return ns.deps.PathSpec.URLize(s), nil + return ns.deps.PathSpec.URLize(ss), nil } -// Anchorize creates sanitized anchor names that are compatible with Blackfriday. -func (ns *Namespace) Anchorize(a any) (string, error) { - s, err := cast.ToStringE(a) +// Anchorize creates sanitized anchor name version of the string s that is compatible +// with how your configured markdown renderer does it. +func (ns *Namespace) Anchorize(s any) (string, error) { + ss, err := cast.ToStringE(s) if err != nil { return "", nil } - return ns.deps.ContentSpec.SanitizeAnchorName(s), nil + return ns.deps.ContentSpec.SanitizeAnchorName(ss), nil } -// Ref returns the absolute URL path to a given content item. -func (ns *Namespace) Ref(in any, args any) (template.HTML, error) { - p, ok := in.(urls.RefLinker) +// Ref returns the absolute URL path to a given content item from Page p. +func (ns *Namespace) Ref(p any, args any) (template.HTML, error) { + pp, ok := p.(urls.RefLinker) if !ok { return "", errors.New("invalid Page received in Ref") } @@ -100,13 +101,13 @@ func (ns *Namespace) Ref(in any, args any) (template.HTML, error) { if err != nil { return "", err } - s, err := p.Ref(argsm) + s, err := pp.Ref(argsm) return template.HTML(s), err } -// RelRef returns the relative URL path to a given content item. -func (ns *Namespace) RelRef(in any, args any) (template.HTML, error) { - p, ok := in.(urls.RefLinker) +// RelRef returns the relative URL path to a given content item from Page p. +func (ns *Namespace) RelRef(p any, args any) (template.HTML, error) { + pp, ok := p.(urls.RefLinker) if !ok { return "", errors.New("invalid Page received in RelRef") } @@ -115,7 +116,7 @@ func (ns *Namespace) RelRef(in any, args any) (template.HTML, error) { return "", err } - s, err := p.RelRef(argsm) + s, err := pp.RelRef(argsm) return template.HTML(s), err } @@ -163,25 +164,25 @@ func (ns *Namespace) refArgsToMap(args any) (map[string]any, error) { }, nil } -// RelLangURL takes a given string and prepends the relative path according to a +// RelLangURL takes the string s and prepends the relative path according to a // page's position in the project directory structure and the current language. -func (ns *Namespace) RelLangURL(a any) (template.HTML, error) { - s, err := cast.ToStringE(a) +func (ns *Namespace) RelLangURL(s any) (template.HTML, error) { + ss, err := cast.ToStringE(s) if err != nil { return "", err } - return template.HTML(ns.deps.PathSpec.RelURL(s, !ns.multihost)), nil + return template.HTML(ns.deps.PathSpec.RelURL(ss, !ns.multihost)), nil } -// AbsLangURL takes a given string and converts it to an absolute URL according +// AbsLangURL the string s and converts it to an absolute URL according // to a page's position in the project directory structure and the current // language. -func (ns *Namespace) AbsLangURL(a any) (template.HTML, error) { - s, err := cast.ToStringE(a) +func (ns *Namespace) AbsLangURL(s any) (template.HTML, error) { + ss, err := cast.ToStringE(s) if err != nil { return "", err } - return template.HTML(ns.deps.PathSpec.AbsURL(s, !ns.multihost)), nil + return template.HTML(ns.deps.PathSpec.AbsURL(ss, !ns.multihost)), nil }