doc: update (#49)

* added more examples and advanced usage guidance
* reformatted go code in markdown
* fixed broken links, misspellings
* added presentation of the approach to testing

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

.claude/CLAUDE.md

@@ -121,9 +121,9 @@ go test ./codegen/internal/... # Scanner and generator tests
 go test ./internal/assertions -run TestEqual
 
 # Run with coverage
-go test -cover ./internal/assertions        # Should be 90%+
-go test -cover ./assert                     # Should be ~100%
-go test -cover ./require                    # Should be ~100%
+go test -cover ./internal/assertions          # Should be 90%+
+go test -cover ./assert                       # Should be ~100%
+go test -cover ./require                      # Should be ~100%
 go test -cover ./codegen/internal/scanner/... # Scanner tests
 
 # Run tests with verbose output
@@ -160,6 +160,11 @@ cd hack/doc-site/hugo
 
 **Example - Adding a new assertion:**
 ```go
+import (
+	"fmt"
+	"strings"
+)
+
 // In internal/assertions/string.go
 
 // StartsWith asserts that the string starts with the given prefix.
@@ -168,16 +173,16 @@ cd hack/doc-site/hugo
 //
 // Examples:
 //
-//   success: "hello world", "hello"
-//   failure: "hello world", "bye"
+//	success: "hello world", "hello"
+//	failure: "hello world", "bye"
 func StartsWith(t T, str, prefix string, msgAndArgs ...any) bool {
-    if h, ok := t.(H); ok {
-        h.Helper()
-    }
-    if !strings.HasPrefix(str, prefix) {
-        return Fail(t, fmt.Sprintf("Expected %q to start with %q", str, prefix), msgAndArgs...)
-    }
-    return true
+	if h, ok := t.(H); ok {
+		h.Helper()
+	}
+	if !strings.HasPrefix(str, prefix) {
+		return Fail(t, fmt.Sprintf("Expected %q to start with %q", str, prefix), msgAndArgs...)
+	}
+	return true
 }
 ```
 
@@ -233,10 +238,10 @@ The generator reads "Examples:" sections from doc comments:
 //
 // Examples:
 //
-//   success: 123, 123
-//   failure: 123, 456
+//	success: 123, 123
+//	failure: 123, 456
 func Equal(t T, expected, actual any, msgAndArgs ...any) bool {
-    // implementation
+	// implementation
 }
 ```
 
@@ -297,10 +302,11 @@ To assign a function to a domain, add a domain tag in its doc comment:
 // domain: equality
 //
 // Examples:
-//   success: 123, 123
-//   failure: 123, 456
+//
+//	success: 123, 123
+//	failure: 123, 456
 func Equal(t T, expected, actual any, msgAndArgs ...any) bool {
-    // implementation
+	// implementation
 }
 ```
 
@@ -396,6 +402,12 @@ This layered approach ensures:
 **This repository uses a signature testing pattern** based on Go 1.23's `iter.Seq` for all table-driven tests:
 
 ```go
+import (
+	"iter"
+	"slices"
+	"testing"
+)
+
 // Define test case struct
 type parseTestExamplesCase struct {
 	name     string

README.md

@@ -81,7 +81,7 @@ go get github.com/go-openapi/testify/v2
 `testify` simplifies your test assertions like so.
 
 ```go
-    import (
+import (
         "testing"
     )
     ...
@@ -101,7 +101,7 @@ go get github.com/go-openapi/testify/v2
 Becomes:
 
 ```go
-    import (
+import (
         "testing"
         "github.com/go-openapi/testify/v2/require"
     )
@@ -190,8 +190,8 @@ Maintainers can cut a new release by either:
 [doc-examples]: https://go-openapi.github.io/testify/usage/examples
 [doc-generics]: https://go-openapi.github.io/testify/usage/generics
 [example-with-generics-url]: https://go-openapi.github.io/testify#usage-with-generics
-[godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/testify
-[godoc-url]: http://pkg.go.dev/github.com/go-openapi/testify
+[godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/testify/v2
+[godoc-url]: https://pkg.go.dev/github.com/go-openapi/testify/v2
 [slack-logo]: https://a.slack-edge.com/e6a93c1/img/icons/favicon-32.png
 [slack-badge]: https://img.shields.io/badge/slack-blue?link=https%3A%2F%2Fgoswagger.slack.com%2Farchives%2FC04R30YM
 [slack-url]: https://goswagger.slack.com/archives/C04R30YMU

codegen/internal/generator/funcmaps/markdown.go

@@ -25,7 +25,6 @@ const sensiblePrealloc = 20
 //  1. Reference-style markdown links: [text]: url
 //  2. Godoc-style links: [errors.Is], [testing.T], etc.
 func FormatMarkdown(in string) string {
-
 	// Step 1: Extract reference-style link definitions
 	// Pattern: [text]: url (at start of line or after whitespace)
 	refLinks := make(map[string]string)

codegen/internal/model/model.go

@@ -133,7 +133,7 @@ func (f Function) GenericName(suffixes ...string) string {
 }
 
 // GenericCallName renders the function name with explicit type parameters.
-// This is used when forwarding type parameters, as all type parameters may not be always infered from the arguments.
+// This is used when forwarding type parameters, as all type parameters may not be always inferred from the arguments.
 func (f Function) GenericCallName(suffixes ...string) string {
 	suffix := strings.Join(suffixes, "")
 	if !f.IsGeneric { // means len(f.TypeParams) == 0

codegen/main.go

@@ -63,6 +63,7 @@ func registerFlags(cfg *config) {
 }
 
 func execute(cfg *config) error {
+	// 1. Scan internal/assertions
 	scanner := scanner.New(
 		scanner.WithWorkDir(cfg.dir),
 		scanner.WithPackage(cfg.inputPkg),
@@ -73,6 +74,7 @@ func execute(cfg *config) error {
 		return err
 	}
 
+	// 2. Generate assert and require packages
 	builder := generator.New(scanned)
 	var doc model.Documentation
 
@@ -105,7 +107,9 @@ func execute(cfg *config) error {
 		return nil
 	}
 
-	// and now for something completely different: generating the documentation
+	// ... and now for something completely different: generating the documentation
+	//
+	// 3. Generate API documentation in docs/doc-site/api
 	documentalist := generator.NewDocGenerator(doc)
 	err = documentalist.Generate(
 		// where to generate

docs/doc-site/_index.md

@@ -20,7 +20,7 @@ This is the go-openapi fork of the great [testify](https://github.com/stretchr/t
 {{% button href="https://github.com/go-openapi/testify/fork" hint="fork me on github" style=primary icon=code-fork %}}Fork me{{% /button %}}
 Design and exploration phase. Feedback, contributions and proposals are welcome.
 
-See our [ROADMAP](./maintainers/ROADMAP.md).
+See our [ROADMAP](./project/maintainers/ROADMAP.md).
 
 ### Motivation
 
@@ -31,7 +31,7 @@ See [why we wanted a v2](./MOTIVATION.md).
 Import this library in your project like so.
 
 ```cmd
-    go get github.com/go-openapi/testify/v2
+go get github.com/go-openapi/testify/v2
 ```
 
 ... and start writing tests. Look at our [examples][doc-examples].
@@ -43,7 +43,7 @@ Import this library in your project like so.
 {{< cards >}}
 {{% card title="Standard library" %}}
 ```go
-    import (
+import (
         "testing"
     )
     ...
@@ -64,7 +64,7 @@ Import this library in your project like so.
 
 {{% card title="testify" %}}
 ```go
-    import (
+import (
         "testing"
 
         "github.com/go-openapi/testify/v2/require"
@@ -91,7 +91,7 @@ Obviously, the `Assertion` type cannot be extended with generic methods, as of `
 {{< cards >}}
 {{% card title="EqualT" %}}
 ```go
-    import (
+import (
         "testing"
 
         "github.com/go-openapi/testify/v2/require"
@@ -107,7 +107,7 @@ Obviously, the `Assertion` type cannot be extended with generic methods, as of `
 {{% /card %}}
 {{% card title="InDeltaT" %}}
 ```go
-    import (
+import (
         "testing"
 
         "github.com/go-openapi/testify/v2/require"