more documentation

Author: lainio

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ### Version history
 
+##### 0.9.5 **mistake in build number: 5 < 41**
+- `flag` package support to set `err2` and `assert` package configuration
+- `err2.Catch` default mode is to log error
+- cleanup and refactoring, new tests and benchmarks
+
 ##### 0.9.41
 - Issue #18: **bug fixed**: noerr-handler had to be the last one of the err2
   handlers

README.md

@@ -527,7 +527,7 @@ Please see the full version history from [CHANGELOG](./CHANGELOG.md).
 
 ### Latest Release
 
-##### 0.9.5
+##### 0.9.51
 - `flag` package support to set `err2` and `assert` package configuration
 - `err2.Catch` default mode is to log error
 - cleanup and refactoring, new tests and benchmarks

assert/assert.go

@@ -17,7 +17,7 @@ import (
 type defInd = uint32
 
 const (
-	// Plain converts asserts just plain error messages without extra
+	// Plain converts asserts just plain K&D error messages without extra
 	// information.
 	Plain defInd = 0 + iota
 
@@ -68,8 +68,12 @@ const (
 	// output properly and allow traverse of locations of the error trace.
 	TestFull
 
-	// Debug asserter transforms assertion violations to panics which is the
-	// pattern that e.g. Go's standard library uses:
+	// Debug asserter transforms assertion violations to panic calls where
+	// panic object's type is string, i.e., err2 package treats it as a normal
+	// panic, not an error.
+	//
+	// The pattern that e.g. Go's standard
+	// library uses:
 	//
 	//   if p == nil {
 	//        panic("pkg: ptr cannot be nil")

assert/doc.go

@@ -58,17 +58,23 @@ The assert package supports Go's flags. All you need to do is to call flag.Parse
 And the following flags are supported (="default-value"):
 
 	-asserter="Prod"
-	    A name of the asserter Plain, Prod, Dev, Debug (see constants)
+	    A name of the asserter Plain, Prod, Dev, Debug
+	    See more information from constants: Plain, Production, Development, Debug
 
 And assert package's configuration flags are inserted.
 
-Note. assert.That's performance is equal to the if-statement. Most of the
-generics-based versions are almost as fast. If your algorithm is
-performance-critical please run `make bench` in the err2 repo and decide case by
-case. Also you can make an issue or even PR if you would like to have something
-similar like glog.V() function.
+# Performance
 
-Note. Format string functions need to be own instances because of Go's vet and
-test tool integration.
+assert.That's performance is equal to the if-statement thanks for inlining. And
+the most of the generics-based versions are about the equally fast.
+
+If your algorithm is performance-critical please run `make bench` in the err2
+repo and decide case by case. Also you can make an issue or even PR if you would
+like to have something similar like glog.V() function.
+
+# Technical Notes
+
+Format string functions need to be own instances because of Go's vet and test
+tool integration.
 */
 package assert

err2_test.go

@@ -912,6 +912,9 @@ func doWork(ePtr *error, r any) {
 	}
 }
 
+// Next benchmark is only for internal test for trying to reproduce Go compilers
+// missing optimization behavior.
+
 func BenchmarkRecursionWithTryAnd_HeavyPtrPtr_Defer(b *testing.B) {
 	var recursion func(a int) (r int, err error)
 	recursion = func(a int) (r int, err error) {

internal/test/test.go

@@ -5,23 +5,23 @@ import (
 	"testing"
 )
 
-// require fails the test if the condition is false.
+// Require fails the test if the condition is false.
 func Require(tb testing.TB, condition bool, v ...interface{}) {
 	tb.Helper()
 	if !condition {
 		tb.Fatal(v...)
 	}
 }
 
-// require fails the test if the condition is false.
+// Requiref fails the test if the condition is false.
 func Requiref(tb testing.TB, condition bool, format string, v ...interface{}) {
 	tb.Helper()
 	if !condition {
 		tb.Fatalf(format, v...)
 	}
 }
 
-// requireEqual fails the test if the values aren't equal
+// RequireEqual fails the test if the values aren't equal
 func RequireEqual[T comparable](tb testing.TB, val, want T, a ...any) {
 	tb.Helper()
 	if want != val {