go documentation update

Author: lainio

assert/assert.go

@@ -28,24 +28,28 @@ const (
 	// name, line number, and caller function.
 	Development
 
-	// Test minimalistic asserter for unit test use. Much more pragmatic is the
-	// TestFull assert that is the default if test asserter isn't given and
-	// still PushTester is called.
-	// Deprecated: Use TestFull instead.
+	// Test minimalistic asserter for unit test use. More pragmatic is the
+	// TestFull asserter (default).
+	//
+	// Use this asserter if your IDE/editor doesn't support long file names, or
+	// for temporary problem solving for your programming environment.
 	Test
 
-	// TestFull assert that is the default if no test asserter is given and
-	// still PushTester is called. The TestFull asserter includes caller info
-	// and call stack to tests similarly like err2's error traces. You need a
-	// proper test result parser like 'github.com/lainio/nvim-go' (fork). Also
-	// most of the make-go-parsers can process the output properly and allow
-	// traverse of locations of the error trace.
-
-	// The call stack produced by these err2/assert test asserts can be used
-	// over package boundaries. For example, if your app and it's sub packages
-	// use err2/asserts for both tests and runtime asserts the results will be
-	// automatically merged. If any of the runtime asserts fails in app tests
-	// from the sub packages the current test fails too.
+	// TestFull asserter (default). The TestFull asserter includes caller info
+	// and call stack for unit testing, similarly like err2's error traces.
+	//
+	// The call stack produced by the test asserts can be used over Go module
+	// boundaries. For example, if your app and it's sub packages both use
+	// err2/assert for unit testing and runtime checks, the runtime assertions
+	// will be automatically converted to test asserts on the fly. If any of
+	// the runtime asserts in sub packages fails during the app tests, the
+	// current app test fails too.
+	//
+	// Note, that the cross-module assertions produce long file names (path
+	// included), and some of the Go test result parsers cannot handle that.
+	// A proper test result parser like 'github.com/lainio/nvim-go' (fork)
+	// works very well. Also most of the make result parsers can process the
+	// output properly and allow traverse of locations of the error trace.
 	TestFull
 
 	// Debug asserter transforms assertion violations to panics which is the
@@ -131,6 +135,11 @@ const (
 //
 // Because PushTester returns PopTester it allows us to merge these two calls to
 // one line. See the first t.Run call. NOTE. More information in PopTester.
+//
+// PushTester allows you to change the current default asserter by accepting it
+// as a second argument. NOTE. That it change the default asserter for whole
+// package. The argument is mainly for temporary development use and isn't not
+// preferrred API usage.
 func PushTester(t testing.TB, a ...defInd) function {
 	if len(a) > 0 {
 		SetDefault(a[0])