context: emphasize panic-free operation in docs

README.md

@@ -63,10 +63,10 @@ to distinguish NaNs from other causes of panic.
 
 On the other hand, Contexts (implemented in the
 [context](https://pkg.go.dev/github.com/db47h/decimal/context?tab=doc)
-sub-package) provide a form of quiet-NaNs whereby any NaN generated by an
-operation will make the context enter into an error state. Further operations
-with the context will be no-ops until (*Context).Err is called to check for
-errors.
+sub-package) provide panic-free operation and a form of quiet-NaNs whereby any
+NaN generated by an operation will make the context enter into an error state.
+Further operations with the context will be no-ops until (*Context).Err is
+called to check for errors.
 
 Mantissae are always normalized, as a result, Decimals have a single possible
 representation:

context/context.go

@@ -19,13 +19,19 @@
 // set z to the result of z.Op(args), rounded using the c's precision and
 // rounding mode and return z.
 //
-// A Context catches NaN errors: if an operation generates a NaN, the operation
-// will silently succeed with an undefined result. Further operations with the
-// context will be no-ops (they simply return the receiver z) until
-// (*Context).Err is called to check for errors.
+// Operations on a Context are panic free: if an operation generates a NaN, the
+// operation will silently succeed with an undefined result (they simply return
+// the receiver z, but its value is undefined). Further operations with the
+// context will be no-ops until (*Context).Err is called to check for errors.
 //
 // Although it does not exactly provide IEEE-754 NaNs, it provides a form of
 // support for quiet NaNs.
+//
+// The idiomatic use is to think of operations between calls to (*Context).Err
+// as a transaction. Operations are done in batches uintil a result is to be
+// output (or re-used in the next iteration of a loop). Calling (*Context).Err
+// at this point determines if the last batch was successful and the result
+// usable. This also readies the Context for the next transaction.
 package context
 
 import (