continuing go doc format fixes, we are almost there

Author: lainio

assert/assert.go

@@ -2,7 +2,7 @@
 Package assert includes runtime assertion helpers both for normal execution as
 well as a assertion package for Go's testing. What makes solution unique is its
 capable to support both modes with the same API. Only thing you need to do is to
-add a PushTester line at the beginning of your unit tests:
+add a [PushTester] line at the beginning of your unit tests:
 
 	func TestInvite(t *testing.T) {
 	     defer assert.PushTester(t)() // push testing variable t beginning of any test
@@ -59,8 +59,8 @@ Please see the code examples for more information.
 
 # Flag Package Support
 
-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"):
+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
@@ -70,15 +70,15 @@ And assert package's configuration flags are inserted.
 
 # Performance
 
-assert.That's performance is equal to the if-statement thanks for inlining. And
+[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. Practice has
-thought that we should prefer other than assert.That because by using detailed
+thought that we should prefer other than [assert.That] because by using detailed
 version like [assert.Shorter] we get precise error messages automatically. Some
 also prefer readability of specific asserters.
 
 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.
+like to have something similar like [glog.V] function.
 
 # Naming
 

assert/doc.go

@@ -31,7 +31,7 @@ them. The CopyFile example shows how it works:
 	     // following try.To check. We place it here that the next deferred
 	     // close is called before our Remove a file call.
 	     defer err2.Handle(&err, err2.Err(func(error) {
-	     	os.Remove(dst)
+	     	try.Out(os.Remove(dst)).Logf("cleanup failed")
 	     }))
 	     defer w.Close()
 
@@ -75,12 +75,23 @@ programmatically (before [flag.Parse] if you are using that):
 	 or
 	err2.SetPanicTracer(log.Writer()) // panic stack trace to std logger
 
-Note. Since [Catch]'s default mode is to catch panics, the panic tracer's
-default values is os.Stderr. The default error tracer is nil.
+Note. Since [Catch]'s default mode is to recover from panics, it's a good
+practice still print their stack trace. The panic tracer's default values is
+[os.Stderr]. The default error tracer is nil.
 
 	err2.SetPanicTracer(os.Stderr) // panic stack tracer's default is stderr
 	err2.SetErrorTracer(nil) // error stack tracer's default is nil
 
+Note, that both panic and error traces are optimized by err2 package. That means
+that the head of the stack trace isn't the panic function, but an actual line
+that caused it. It works for all three categories:
+  - normal error values
+  - [runtime.Error] values
+  - any types of the panics
+
+The last two types are handled as panics in the error handling functions given
+to [Handle] and [Catch].
+
 # Automatic Logging
 
 Same err2 capablities support automatic logging like the [Catch] and

doc.go

@@ -14,8 +14,8 @@ type (
 	Handler = handler.ErrorFn
 )
 
-// Sentinel error value helpers. They are convenient thanks to [try.IsNotFound]
-// and similar functions.
+// Sentinel error value helpers. They are convenient thanks to
+// [github.com/lainio/err2/try.IsNotFound] and similar functions.
 //
 // [ErrNotFound] ... [ErrNotEnabled] are similar no-error like [io.EOF] for
 // those who really want to use error return values to transport non errors.
@@ -38,7 +38,7 @@ var (
 )
 
 // Stdnull implements [io.Writer] that writes nothing, e.g.,
-// [SetLogTracer] in cases you don't want to use automatic log writer,
+// [SetLogTracer] in cases you don't want to use automatic log writer (=nil),
 // i.e., [LogTracer] == /dev/null. It can be used to change how the [Catch]
 // works, e.g., in CLI apps.
 var Stdnull = &nullDev{}
@@ -145,7 +145,7 @@ func Handle(err *error, a ...any) {
 // cleanups, etc. The error handler function has same signature as Handle's
 // error handling function [Handler]. By returning nil resets the
 // error, which allows e.g. prevent automatic error logs to happening.
-// Otherwise, the output results depends on the current [Tracer] and assert
+// Otherwise, the output results depends on the current trace and assert
 // settings. The default trace setting prints call stacks for panics but not for
 // errors:
 //
@@ -155,15 +155,15 @@ func Handle(err *error, a ...any) {
 //
 //	defer err2.Catch(err2.Noop)
 //
-// You can have unlimited amount of error handlers. They are called if error
+// You can give unlimited amount of error handlers. They are called if error
 // happens and they are called in the same order as they are given or until one
 // of them resets the error like [Reset] in the next sample:
 //
 //	defer err2.Catch(err2.Noop, err2.Reset, err2.Log) // err2.Log not called!
 //
-// The last one calls your error handler, and you have an explicit panic handler
-// as well, where you can e.g. continue panicking to propagate it for above
-// callers or stop it like below:
+// The next sample calls your error handler, and you have an explicit panic
+// handler as well, where you can e.g. continue panicking to propagate it for
+// above callers or stop it like below:
 //
 //	defer err2.Catch(func(err error) error { return err }, func(p any) {})
 func Catch(a ...any) {
@@ -183,7 +183,7 @@ func Catch(a ...any) {
 	doTrace(err)
 }
 
-// Throwf builds and throws (panics) an error. For creation it's similar to
+// Throwf builds and throws an error (panic). For creation it's similar to
 // [fmt.Errorf]. Because panic is used to transport the error instead of error
 // return value, it's called only if you want to non-local control structure for
 // error handling, i.e. your current function doesn't have error return value.

err2.go

@@ -10,8 +10,12 @@ func init() {
 }
 
 // SetFormatter sets the current formatter for the err2 package. The default
-// formatter.Decamel tries to process function names to human readable and the
-// idiomatic Go format, i.e. all lowercase, space delimiter, etc.
+// [formatter.Decamel] processes function names to human readable and the
+// idiomatic Go format, i.e. all lowercase, space delimiter, package names colon
+// separated. The example how a quite complex method name gives a proper error
+// message prefix:
+//
+//	"ssi.(*DIDAgent).CreateWallet" -> "ssi: didagent create wallet"
 //
 // Following line sets a noop formatter where errors are taken as function names
 // are in the call stack.

formatter.go

@@ -24,18 +24,18 @@ type Formatter struct {
 	DoFmt
 }
 
-var (
-	// Decamel is preimplemented and default formatter to produce human
-	// readable error strings from function names.
-	//   func CopyFile(..)  -> "copy file: file not exists"
-	//                          ^-------^ -> generated from CopyFile
-	Decamel = &Formatter{DoFmt: str.Decamel}
+// Decamel is preimplemented and default formatter to produce human
+// readable error strings from function names.
+//
+//	func CopyFile(..)  -> "copy file: file not exists"
+//	                       ^-------^ -> generated from 'func CopyFile'
+var Decamel = &Formatter{DoFmt: str.Decamel}
 
-	// Noop is preimplemented formatter that does nothing to function name.
-	//   func CopyFile(..)  -> "CopyFile: file not exists"
-	//                          ^------^ -> function name as it is: CopyFile
-	Noop = &Formatter{DoFmt: func(i string) string { return i }}
-)
+// Noop is preimplemented formatter that does nothing to function name.
+//
+//	func CopyFile(..)  -> "CopyFile: file not exists"
+//	                       ^------^ -> function name as it is: CopyFile
+var Noop = &Formatter{DoFmt: func(i string) string { return i }}
 
 // Format just calls function set in the DoFmt field.
 func (f *Formatter) Format(input string) string {