doc: increased godoc coverage, added testable examples

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

Author: fredbi

.gitignore

@@ -1,2 +1,3 @@
 secrets.yml
-coverage.out
+*.out
+settings.local.json

api.go

@@ -28,10 +28,12 @@ type apiError struct {
 	message string
 }
 
+// Error implements the standard error interface.
 func (a *apiError) Error() string {
 	return a.message
 }
 
+// Code returns the HTTP status code associated with this error.
 func (a *apiError) Code() int32 {
 	return a.code
 }
@@ -78,11 +80,12 @@ type MethodNotAllowedError struct {
 	message string
 }
 
+// Error implements the standard error interface.
 func (m *MethodNotAllowedError) Error() string {
 	return m.message
 }
 
-// Code the error code.
+// Code returns 405 (Method Not Allowed) as the HTTP status code.
 func (m *MethodNotAllowedError) Code() int32 {
 	return m.code
 }

examples_test.go

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package errors_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/go-openapi/errors"
+)
+
+func ExampleNew() {
+	// Create a generic API error with custom code
+	err := errors.New(400, "invalid input: %s", "email")
+	fmt.Printf("error: %v\n", err)
+	fmt.Printf("code: %d\n", err.Code())
+
+	// Create common HTTP errors
+	notFound := errors.NotFound("user %s not found", "john-doe")
+	fmt.Printf("not found: %v\n", notFound)
+	fmt.Printf("not found code: %d\n", notFound.Code())
+
+	notImpl := errors.NotImplemented("feature: dark mode")
+	fmt.Printf("not implemented: %v\n", notImpl)
+
+	// Output:
+	// error: invalid input: email
+	// code: 400
+	// not found: user john-doe not found
+	// not found code: 404
+	// not implemented: feature: dark mode
+}
+
+func ExampleServeError() {
+	// Create a simple validation error
+	err := errors.Required("email", "body", nil)
+
+	// Simulate HTTP response
+	recorder := httptest.NewRecorder()
+	request := httptest.NewRequest(http.MethodPost, "/api/users", nil)
+
+	// Serve the error as JSON
+	errors.ServeError(recorder, request, err)
+
+	fmt.Printf("status: %d\n", recorder.Code)
+	fmt.Printf("content-type: %s\n", recorder.Header().Get("Content-Type"))
+
+	// Parse and display the JSON response
+	var response map[string]any
+	if err := json.Unmarshal(recorder.Body.Bytes(), &response); err == nil {
+		fmt.Printf("error code: %.0f\n", response["code"])
+		fmt.Printf("error message: %s\n", response["message"])
+	}
+
+	// Output:
+	// status: 422
+	// content-type: application/json
+	// error code: 602
+	// error message: email in body is required
+}
+
+func ExampleCompositeValidationError() {
+	var errs []error
+
+	// Collect multiple validation errors
+	errs = append(errs, errors.Required("name", "body", nil))
+	errs = append(errs, errors.TooShort("description", "body", 10, "short"))
+	errs = append(errs, errors.InvalidType("age", "body", "integer", "abc"))
+
+	// Combine them into a composite error
+	compositeErr := errors.CompositeValidationError(errs...)
+
+	fmt.Printf("error count: %d\n", len(errs))
+	fmt.Printf("composite error: %v\n", compositeErr)
+	fmt.Printf("code: %d\n", compositeErr.Code())
+
+	// Can unwrap to access individual errors
+	if unwrapped := compositeErr.Unwrap(); unwrapped != nil {
+		fmt.Printf("unwrapped count: %d\n", len(unwrapped))
+	}
+
+	// Output:
+	// error count: 3
+	// composite error: validation failure list:
+	// name in body is required
+	// description in body should be at least 10 chars long
+	// age in body must be of type integer: "abc"
+	// code: 422
+	// unwrapped count: 3
+}

headers.go

@@ -19,11 +19,13 @@ type Validation struct { //nolint: errname // changing the name to abide by the
 	Values  []any
 }
 
+// Error implements the standard error interface.
 func (e *Validation) Error() string {
 	return e.message
 }
 
-// Code the error code.
+// Code returns the HTTP status code for this validation error.
+// Returns 422 (Unprocessable Entity) by default.
 func (e *Validation) Code() int32 {
 	return e.code
 }

middleware.go

@@ -17,6 +17,7 @@ type APIVerificationFailed struct { //nolint: errname
 	MissingRegistration  []string `json:"missingRegistration,omitempty"`
 }
 
+// Error implements the standard error interface.
 func (v *APIVerificationFailed) Error() string {
 	buf := bytes.NewBuffer(nil)
 

parsing.go

@@ -37,11 +37,12 @@ func NewParseError(name, in, value string, reason error) *ParseError {
 	}
 }
 
+// Error implements the standard error interface.
 func (e *ParseError) Error() string {
 	return e.message
 }
 
-// Code returns the http status code for this error.
+// Code returns 400 (Bad Request) as the HTTP status code for parsing errors.
 func (e *ParseError) Code() int32 {
 	return e.code
 }

schema.go

@@ -71,6 +71,7 @@ const (
 
 	// InvalidTypeCode is used for any subclass of invalid types.
 	InvalidTypeCode = maximumValidHTTPCode + iota
+	// RequiredFailCode indicates a required field is missing.
 	RequiredFailCode
 	TooLongFailCode
 	TooShortFailCode
@@ -98,11 +99,12 @@ type CompositeError struct {
 	message string
 }
 
-// Code for this error.
+// Code returns the HTTP status code for this composite error.
 func (c *CompositeError) Code() int32 {
 	return c.code
 }
 
+// Error implements the standard error interface.
 func (c *CompositeError) Error() string {
 	if len(c.Errors) > 0 {
 		msgs := []string{c.message + ":"}
@@ -117,6 +119,7 @@ func (c *CompositeError) Error() string {
 	return c.message
 }
 
+// Unwrap implements the [errors.Unwrap] interface.
 func (c *CompositeError) Unwrap() []error {
 	return c.Errors
 }