Add readme about new features, improve comments, and add an corner test case

Author: rwxe

README.md

@@ -2,19 +2,19 @@
 # overflow
 Check for integer overflow in Golang arithmetic and type conversion.
 ### Install
-```
+```sh
 go get github.com/johncgriffin/overflow
 ```
 Note that because Go has no template types, the majority of repetitive code is 
 generated by overflow_template.sh.  If you have to change an
 algorithm, change it there and regenerate the Go code via:
-```
+```sh
 go generate
 ```
 ### Synopsis
 
 #### Arithmetic overflow detection
-```
+```go
 package main
 
 import "fmt"
@@ -34,7 +34,7 @@ func main() {
 }
 ```
 yields the output
-```
+```go
 9223372036854775802+0 -> (9223372036854775802,true)
 9223372036854775802+1 -> (9223372036854775803,true)
 9223372036854775802+2 -> (9223372036854775804,true)
@@ -51,7 +51,7 @@ For (u)int types, provide (U)Add, (U)Sub, (U)Mul, (U)Div, (U)Quotient, etc.
 
 
 #### Type conversion overflow detection
-```
+```go
 func main() {
 	var i uint
 	for i = math.MaxInt - 5; i <= math.MaxInt+5; i++ {
@@ -62,7 +62,7 @@ func main() {
 }
 ```
 yields the output
-```
+```go
 9223372036854775802 -> (9223372036854775802,true)
 9223372036854775803 -> (9223372036854775803,true)
 9223372036854775804 -> (9223372036854775804,true)
@@ -83,6 +83,27 @@ There's a good case to be made that a panic is an unidiomatic but proper respons
 believe that there's no valid way to continue your program after math goes wayward, you can
 use the easier Addp, Mulp, Subp, and Divp versions which return the normal result or panic.
 
+### Performance considerations
+
+Compared with the integer type safety libraries of other languages (such as C++), this
+library uses some seemingly slow operations, such as division. But this does not mean that
+these methods will be slow, on the contrary, it will be faster than complex implementations
+in other languages. The reason is that Go does not allow forced inlining, and any complex
+functions will be abandoned for inlining, resulting in additional calling overhead. Short
+functions are lightning fast due to automatic inlining. For example, for unsigned 64-bit
+integer multiplication overflow detection, when inlining is disabled, division takes five
+times as long as long multiplication, but after automatic inlining is allowed, division
+takes 1/5 of long multiplication.
+
+Note that using `//go:noinline` in your business function will not affect the inlining of
+the library function. Only disabling global inlining through `-gcflags="-l"` will affect the
+inlining of this library function.
+
+### Basis and dependencies
+
+This library is based on Go's official compiler implementation and language specification,
+which defines the behavior when integer overflow occurs.
+
 
 - - -
 MIT License

overflow.go

@@ -42,7 +42,7 @@ So, FEEL FREE to carefully review the code visually.
 
 // Unspecified size, i.e. normal signed int
 
-// Add sums two ints, returning the result and a boolean status.
+// Add sums two ints, returning the result and a ok result indicating whether the operation is safe.
 func Add(a, b int) (int, bool) {
 	if _is64Bit() {
 		r64, ok := Add64(int64(a), int64(b))
@@ -52,7 +52,7 @@ func Add(a, b int) (int, bool) {
 	return int(r32), ok
 }
 
-// UAdd sums two uints, returning the result and a boolean status.
+// UAdd sums two uints, returning the result and a ok result indicating whether the operation is safe.
 func UAdd(a, b uint) (uint, bool) {
 	if _is64Bit() {
 		r64, ok := UAdd64(uint64(a), uint64(b))
@@ -62,7 +62,7 @@ func UAdd(a, b uint) (uint, bool) {
 	return uint(r32), ok
 }
 
-// Sub returns the difference of two ints and a boolean status.
+// Sub returns the difference of two ints and a ok result indicating whether the operation is safe.
 func Sub(a, b int) (int, bool) {
 	if _is64Bit() {
 		r64, ok := Sub64(int64(a), int64(b))
@@ -72,7 +72,7 @@ func Sub(a, b int) (int, bool) {
 	return int(r32), ok
 }
 
-// USub returns the difference of two uints and a boolean status.
+// USub returns the difference of two uints and a ok result indicating whether the operation is safe.
 func USub(a, b uint) (uint, bool) {
 	if _is64Bit() {
 		r64, ok := USub64(uint64(a), uint64(b))
@@ -82,7 +82,7 @@ func USub(a, b uint) (uint, bool) {
 	return uint(r32), ok
 }
 
-// Mul returns the product of two ints and a boolean status.
+// Mul returns the product of two ints and a ok result indicating whether the operation is safe.
 func Mul(a, b int) (int, bool) {
 	if _is64Bit() {
 		r64, ok := Mul64(int64(a), int64(b))
@@ -92,7 +92,7 @@ func Mul(a, b int) (int, bool) {
 	return int(r32), ok
 }
 
-// UMul returns the product of two uints and a boolean status.
+// UMul returns the product of two uints and a ok result indicating whether the operation is safe.
 func UMul(a, b uint) (uint, bool) {
 	if _is64Bit() {
 		r64, ok := UMul64(uint64(a), uint64(b))
@@ -102,7 +102,7 @@ func UMul(a, b uint) (uint, bool) {
 	return uint(r32), ok
 }
 
-// Div returns the quotient of two ints and a boolean status
+// Div returns the quotient of two ints and a ok result indicating whether the operation is safe.
 func Div(a, b int) (int, bool) {
 	if _is64Bit() {
 		r64, ok := Div64(int64(a), int64(b))
@@ -112,7 +112,7 @@ func Div(a, b int) (int, bool) {
 	return int(r32), ok
 }
 
-// UDiv returns the quotient of two uints and a boolean status
+// UDiv returns the quotient of two uints and a ok result indicating whether the operation is safe.
 func UDiv(a, b uint) (uint, bool) {
 	if _is64Bit() {
 		r64, ok := UDiv64(uint64(a), uint64(b))
@@ -122,7 +122,7 @@ func UDiv(a, b uint) (uint, bool) {
 	return uint(r32), ok
 }
 
-// Quotient returns the quotient, remainder and status of two ints
+// Quotient returns the quotient, remainder and ok result indicating whether the operation is safe.
 func Quotient(a, b int) (int, int, bool) {
 	if _is64Bit() {
 		q64, r64, ok := Quotient64(int64(a), int64(b))
@@ -132,7 +132,7 @@ func Quotient(a, b int) (int, int, bool) {
 	return int(q32), int(r32), ok
 }
 
-// UQuotient returns the quotient, remainder and status of two uints
+// UQuotient returns the quotient, remainder and ok result indicating whether the operation is safe.
 func UQuotient(a, b uint) (uint, uint, bool) {
 	if _is64Bit() {
 		uq64, ur64, ok := UQuotient64(uint64(a), uint64(b))