docs: td uses new go1.19 doc features

Signed-off-by: Maxime Soulé <btik-git@scoubidou.com>

Author: maxatome

README.md

@@ -286,7 +286,7 @@ See [FAQ](https://go-testdeep.zetta.rocks/faq/).
 [`tdutil`]: https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdutil
 
 [`BeLax` config flag]: https://pkg.go.dev/github.com/maxatome/go-testdeep/td#ContextConfig.BeLax
-[`error`]: https://pkg.go.dev/builtin/#error
+[`error`]: https://pkg.go.dev/builtin#error
 
 
 [`fmt.Stringer`]: https://pkg.go.dev/fmt/#Stringer

helpers/tdhttp/doc.go

@@ -4,10 +4,10 @@
 // This source code is licensed under the BSD-style license found in the
 // LICENSE file in the root directory of this source tree.
 
-// Package tdhttp provides some functions to easily test HTTP handlers.
+// Package tdhttp, from [go-testdeep], provides some functions to easily
+// test HTTP handlers.
 //
-// Combined to td package ([github.com/maxatome/go-testdeep/td]) it
-// provides powerful testing features.
+// Combined to [td] package it provides powerful testing features.
 //
 // # TestAPI
 //
@@ -62,4 +62,6 @@
 // It now uses [TestAPI] behind the scene. It is better to directly
 // use [TestAPI] and its methods instead, as it is more flexible and
 // readable.
+//
+// [go-testdeep]: https://go-testdeep.zetta.rocks/
 package tdhttp

helpers/tdhttp/http.go

@@ -271,8 +271,8 @@ func CmpXMLResponse(t testing.TB,
 }
 
 // CmpMarshaledResponseFunc returns a function ready to be used with
-// [testing.Run], calling [CmpMarshaledResponse] behind the scene. As it
-// is intended to be used in conjunction with [testing.Run] which
+// [testing.T.Run], calling [CmpMarshaledResponse] behind the scene. As it
+// is intended to be used in conjunction with [testing.T.Run] which
 // names the sub-test, the test name part (args...) is voluntary
 // omitted.
 //
@@ -297,8 +297,8 @@ func CmpMarshaledResponseFunc(req *http.Request,
 }
 
 // CmpResponseFunc returns a function ready to be used with
-// [testing.Run], calling [CmpResponse] behind the scene. As it is
-// intended to be used in conjunction with [testing.Run] which names
+// [testing.T.Run], calling [CmpResponse] behind the scene. As it is
+// intended to be used in conjunction with [testing.T.Run] which names
 // the sub-test, the test name part (args...) is voluntary omitted.
 //
 //	t.Run("Subtest name", tdhttp.CmpResponseFunc(
@@ -321,8 +321,8 @@ func CmpResponseFunc(req *http.Request,
 }
 
 // CmpJSONResponseFunc returns a function ready to be used with
-// [testing.Run], calling [CmpJSONResponse] behind the scene. As it is
-// intended to be used in conjunction with [testing.Run] which names
+// [testing.T.Run], calling [CmpJSONResponse] behind the scene. As it is
+// intended to be used in conjunction with [testing.T.Run] which names
 // the sub-test, the test name part (args...) is voluntary omitted.
 //
 //	t.Run("Subtest name", tdhttp.CmpJSONResponseFunc(
@@ -346,8 +346,8 @@ func CmpJSONResponseFunc(req *http.Request,
 }
 
 // CmpXMLResponseFunc returns a function ready to be used with
-// [testing.Run], calling [CmpXMLResponse] behind the scene. As it is
-// intended to be used in conjunction with [testing.Run] which names
+// [testing.T.Run], calling [CmpXMLResponse] behind the scene. As it is
+// intended to be used in conjunction with [testing.T.Run] which names
 // the sub-test, the test name part (args...) is voluntary omitted.
 //
 //	t.Run("Subtest name", tdhttp.CmpXMLResponseFunc(

helpers/tdsuite/doc.go

@@ -4,7 +4,7 @@
 // This source code is licensed under the BSD-style license found in the
 // LICENSE file in the root directory of this source tree.
 
-// Package tdsuite adds tests suite feature to go-testdeep in a
+// Package tdsuite adds tests suite feature to [go-testdeep] in a
 // non-intrusive way, but easily and powerfully.
 //
 // A tests suite is a set of tests run sequentially that share some data.
@@ -125,4 +125,6 @@
 //
 // See documentation below for other possible hooks: [PreTest], [PostTest]
 // and [BetweenTests].
+//
+// [go-testdeep]: https://go-testdeep.zetta.rocks/
 package tdsuite

helpers/tdutil/t.go

@@ -17,7 +17,7 @@ import (
 )
 
 // T can be used in tests, to test [testing.T] behavior as it overrides
-// [testing.Run] method.
+// [testing.T.Run] method.
 type T struct {
 	testing.T
 	name string

internal/anchors/anchor.go

@@ -27,7 +27,7 @@ type Info struct {
 	anchors map[any]anchor
 }
 
-// NewInfo returns a new instance of *Info.
+// NewInfo returns a new instance of [*Info].
 func NewInfo() *Info {
 	return &Info{
 		anchors: map[any]anchor{},

internal/anchors/types.go

@@ -22,7 +22,7 @@ type anchorableType struct {
 }
 
 // AnchorableTypes contains all non-native types that can be
-// anchorable. See AddAnchorableStructType to add a new type to it.
+// anchorable. See [AddAnchorableStructType] to add a new type to it.
 var AnchorableTypes []anchorableType
 
 func init() {
@@ -31,29 +31,29 @@ func init() {
 	})
 }
 
-// AddAnchorableStructType declares a struct type as anchorable. "fn"
+// AddAnchorableStructType declares a struct type as anchorable. fn
 // is a function allowing to return a unique and identifiable instance
 // of the struct type.
 //
-// "fn" has to have the following signature:
+// fn has to have the following signature:
 //
 //	func (nextAnchor int) TYPE
 //
-// TYPE is the struct type to make anchorable and "nextAnchor" is an
+// TYPE is the struct type to make anchorable and nextAnchor is an
 // index to allow to differentiate several instances of the same type.
 //
-// For example, the time.Time type which is anchorable by default,
+// For example, the [time.Time] type which is anchorable by default,
 // is declared as:
 //
 //	AddAnchorableStructType(func (nextAnchor int) time.Time {
 //	  return time.Unix(math.MaxInt64-1000424443-int64(nextAnchor), 42)
 //	})
 //
 // Just as a note, the 1000424443 constant allows to avoid to flirt
-// with the math.MaxInt64 extreme limit and so avoid possible
+// with the [math.MaxInt64] extreme limit and so avoid possible
 // collision with real world values.
 //
-// It returns an error if the provided "fn" is not a function or if it
+// It returns an error if the provided fn is not a function or if it
 // has not the expected signature (see above).
 func AddAnchorableStructType(fn any) error {
 	vfn := reflect.ValueOf(fn)

internal/color/color.go

@@ -75,7 +75,7 @@ func Init() {
 }
 
 // SaveState saves the "TESTDEEP_COLOR" environment variable
-// value, sets it to "on" (if true passed as on) or "false" (if on not
+// value, sets it to "on" (if true passed as on) or "off" (if on not
 // passed or set to false), resets the colors initialization and
 // returns a function to be called in a defer statement. Only intended
 // to be used in tests like:
@@ -249,7 +249,7 @@ func TooManyParams(usage string) string {
 	return BadOnBold + "usage: " + usage + ", too many parameters" + BadOff
 }
 
-// UnBad returns "s" with bad color prefix & suffix removed.
+// UnBad returns s with bad color prefix & suffix removed.
 func UnBad(s string) string {
 	return strings.TrimSuffix(strings.TrimPrefix(s, BadOnBold), BadOff)
 }

internal/ctxerr/context.go

@@ -15,7 +15,7 @@ import (
 	"github.com/maxatome/go-testdeep/internal/visited"
 )
 
-// Context is used internally to keep track of the CmpDeeply in-Depth
+// Context is used internally to keep track of the Cmp in-depth
 // traversal.
 type Context struct {
 	Path        Path
@@ -46,7 +46,7 @@ type Context struct {
 	IgnoreUnexported bool
 }
 
-// InitErrors initializes Context *Errors slice, if MaxErrors < 0 or
+// InitErrors initializes [Context] *Errors slice, if MaxErrors < 0 or
 // MaxErrors > 1.
 func (c *Context) InitErrors() {
 	if c.MaxErrors != 0 && c.MaxErrors != 1 {
@@ -55,7 +55,7 @@ func (c *Context) InitErrors() {
 	}
 }
 
-// ResetErrors returns a new Context without any Error set.
+// ResetErrors returns a new [Context] without any Error set.
 func (c Context) ResetErrors() (new Context) {
 	new = c
 	new.InitErrors()
@@ -65,7 +65,8 @@ func (c Context) ResetErrors() (new Context) {
 // CollectError collects an error in the context. It returns an error
 // if the collector is full, nil otherwise.
 //
-// In boolean context, ignore the passed error and return the BooleanError.
+// In boolean context, it ignores the passed error and returns the
+// [BooleanError].
 func (c Context) CollectError(err *Error) *Error {
 	if err == nil {
 		return nil
@@ -126,23 +127,23 @@ func (c Context) CannotCompareError() *Error {
 	}
 }
 
-// AddCustomLevel creates a new Context from current one plus pathAdd.
+// AddCustomLevel creates a new [Context] from current one plus pathAdd.
 func (c Context) AddCustomLevel(pathAdd string) (new Context) {
 	new = c
 	new.Path = new.Path.AddCustomLevel(pathAdd)
 	new.Depth++
 	return
 }
 
-// AddField creates a new Context from current one plus "." + field.
+// AddField creates a new [Context] from current one plus "." + field.
 func (c Context) AddField(field string) (new Context) {
 	new = c
 	new.Path = new.Path.AddField(field)
 	new.Depth++
 	return
 }
 
-// AddArrayIndex creates a new Context from current one plus an array
+// AddArrayIndex creates a new [Context] from current one plus an array
 // dereference for index-th item.
 func (c Context) AddArrayIndex(index int) (new Context) {
 	new = c
@@ -151,7 +152,7 @@ func (c Context) AddArrayIndex(index int) (new Context) {
 	return
 }
 
-// AddMapKey creates a new Context from current one plus a map
+// AddMapKey creates a new [Context] from current one plus a map
 // dereference for key key.
 func (c Context) AddMapKey(key any) (new Context) {
 	new = c
@@ -160,15 +161,15 @@ func (c Context) AddMapKey(key any) (new Context) {
 	return
 }
 
-// AddPtr creates a new Context from current one plus a pointer dereference.
+// AddPtr creates a new [Context] from current one plus a pointer dereference.
 func (c Context) AddPtr(num int) (new Context) {
 	new = c
 	new.Path = new.Path.AddPtr(num)
 	new.Depth++
 	return
 }
 
-// AddFunctionCall creates a new Context from current one inside a
+// AddFunctionCall creates a new [Context] from current one inside a
 // function call.
 func (c Context) AddFunctionCall(fn string) (new Context) {
 	new = c
@@ -177,7 +178,7 @@ func (c Context) AddFunctionCall(fn string) (new Context) {
 	return
 }
 
-// ResetPath creates a new Context from current one but reinitializing Path.
+// ResetPath creates a new [Context] from current one but reinitializing Path.
 func (c Context) ResetPath(newRoot string) (new Context) {
 	new = c
 	new.Path = NewPath(newRoot)

internal/ctxerr/error.go

@@ -38,17 +38,15 @@ type Error struct {
 	Next *Error
 }
 
-var (
-	// BooleanError is the *Error returned when an error occurs in a
-	// boolean context.
-	BooleanError = &Error{}
-
-	// ErrTooManyErrors is chained to the last error encountered when
-	// the maximum number of errors has been reached.
-	ErrTooManyErrors = &Error{
-		Message: "Too many errors (use TESTDEEP_MAX_ERRORS=-1 to see all)",
-	}
-)
+// BooleanError is the [*Error] returned when an error occurs in a
+// boolean context.
+var BooleanError = &Error{}
+
+// ErrTooManyErrors is chained to the last error encountered when
+// the maximum number of errors has been reached.
+var ErrTooManyErrors = &Error{
+	Message: "Too many errors (use TESTDEEP_MAX_ERRORS=-1 to see all)",
+}
 
 // TypeMismatch returns a "type mismatch" error. It is the caller
 // responsibility to check that both types differ.
@@ -101,8 +99,8 @@ func (e *Error) Error() string {
 	return buf.String()
 }
 
-// Append appends the Error contents to "buf" using prefix "prefix"
-// for each line.
+// Append appends the a contents to buf using prefix prefix for each
+// line.
 func (e *Error) Append(buf *bytes.Buffer, prefix string) {
 	if e == BooleanError {
 		return
@@ -187,8 +185,7 @@ func (e *Error) Append(buf *bytes.Buffer, prefix string) {
 }
 
 // GotString returns the string corresponding to the Got
-// field. Returns the empty string if the Error Summary field is not
-// nil.
+// field. Returns the empty string if the e Summary field is not nil.
 func (e *Error) GotString() string {
 	if e.Summary != nil {
 		return ""
@@ -197,8 +194,7 @@ func (e *Error) GotString() string {
 }
 
 // ExpectedString returns the string corresponding to the Expected
-// field. Returns the empty string if the Error Summary field is not
-// nil.
+// field. Returns the empty string if the e Summary field is not nil.
 func (e *Error) ExpectedString() string {
 	if e.Summary != nil {
 		return ""
@@ -207,7 +203,7 @@ func (e *Error) ExpectedString() string {
 }
 
 // SummaryString returns the string corresponding to the Summary
-// field. Returns the empty string if the Error Summary field is nil.
+// field. Returns the empty string if the e Summary field is nil.
 func (e *Error) SummaryString() string {
 	if e.Summary == nil {
 		return ""