pkg lvl documentations for err2, assert, and try

Author: lainio

assert/doc.go

@@ -10,23 +10,30 @@ add following two lines at the beginning of your unit tests:
 	     alice.Node = root1.Invite(alice.Node, root1.Key, alice.PubKey, 1)
 	     assert.Equal(alice.Len(), 1) // assert anything normally
 
-# Merge Runtime And Test Assertions
+# Merge Runtime And Unit Test Assertions
 
 Especially powerful feature is that even if some assertion violation happens
-during the execution of called functions not the test it self. See the above
-example. If assertion failure happens inside of the Invite() function instead of
-the actual Test function, TestInvite, it's still reported correctly as normal
-test failure when TestInvite is executed. It doesn't matter how deep the
-recursion is, or if parallel test runs are performed. It works just as you
-hoped.
+during the execution of called functions not the test function itself. See the
+above example. If assertion failure happens inside of the Invite() function
+instead of the actual test function, TestInvite, it's still reported correctly
+as normal test failure when TestInvite unit test is executed. It doesn't matter
+how deep the recursion is, or if parallel test runs are performed. It works just
+as you hoped.
+
+This is the actual Invite function implementation's first two lines. Even the
+assertion line is written more for runtime detection and active comment, it
+catches all unit test errors as well:
+
+	func (c Chain) Invite(...) {
+		assert.That(c.isLeaf(invitersKey), "only leaf can invite")
 
 # Call Stack Traversal During tests
 
 The asserter package has super powerful feature. It allows us track assertion
 violations over package and even module boundaries. When using err2 assert
-package for runtime Asserts and assert violation happens in what ever package
-and module, the whole call stack is brougth to unit test logs. Naturally this is
-optinal. Only thing you need to do is set proper asserter and call PushTester.
+package for runtime Asserts and assert violation happens in whatever package
+and module, the whole call stack is brought to unit test logs. Naturally this is
+optional. Only thing you need to do is set proper asserter and call PushTester.
 
 	// use unit testing asserter
 	assert.SetDefault(assert.TestFull)
@@ -66,15 +73,19 @@ And assert package's configuration flags are inserted.
 # Performance
 
 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.
+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
+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.
 
-# Technical Notes
+# Naming
 
-Format string functions need to be own instances because of Go's vet and test
-tool integration.
+Because performance has been number one requirement and Go's generics cannot
+discrete slices, maps and channels we have used naming prefixes accordingly: S =
+slice, M = map, C = channel. No prefix is (currently) for the string type.
 */
 package assert

doc.go

@@ -67,9 +67,12 @@ the try package documentation for more information about the error checks.
 
 # Automatic Stack Tracing
 
-err2 offers optional stack tracing. And yes, it's fully automatic. Just set the
-tracers at the beginning your app, e.g. main function, to the stream you want
-traces to be written:
+err2 offers optional stack tracing. And yes, it's fully automatic. Just call
+
+	flag.Parse() # this is enough for err2 pkg to add its flags
+
+at the beginning your app, e.g. main function, or set the tracers
+programmatically (before flag.Parse if you are using that):
 
 	err2.SetErrorTracer(os.Stderr) // write error stack trace to stderr
 	 or

try/try.go

@@ -10,7 +10,7 @@ about err2 and try packager roles can be seen in the FileCopy example:
 
 	w := try.To1(os.Create(dst))
 	defer err2.Handle(&err, func(error) error {
-	     try.To(os.Remove(dst)).Logf()
+	     try.Out(os.Remove(dst)).Logf()
 	     return nil
 	})
 	defer w.Close()