Merge pull request #116 from omarkohl/master

Document intended differences between WithHint and WithDetail (#114)

Author: knz

README.md

@@ -209,12 +209,12 @@ return errors.Wrap(foo(), "foo")
   - how to access the detail: `Error()`, regular Go formatting, Sentry Report.
 
 - `WithDetail(error, string) error`, `WithDetailf(error, string, ...interface{}) error`, user-facing detail with contextual information.
-  - **when to use: need to embark a message string to output when the error is presented to a human.**
+  - **when to use: need to embark a message string to output when the error is presented to a developer.**
   - what it does: captures detail strings.
   - how to access the detail: `errors.GetAllDetails()`, `errors.FlattenDetails()` (all details are preserved), format with `%+v`. Not included in Sentry reports.
 
 - `WithHint(error, string) error`, `WithHintf(error, string, ...interface{}) error`: user-facing detail with suggestion for action to take.
-  - **when to use: need to embark a message string to output when the error is presented to a human.**
+  - **when to use: need to embark a message string to output when the error is presented to an end user.**
   - what it does: captures hint strings.
   - how to access the detail: `errors.GetAllHints()`, `errors.FlattenHints()` (hints are de-duplicated), format with `%+v`. Not included in Sentry reports.
 

hintdetail/hintdetail.go

@@ -23,6 +23,7 @@ import (
 
 // WithHint decorates an error with a textual hint.
 // The hint may contain PII and thus will not reportable.
+// The suggested use case for hint is to relay information to end users.
 //
 // Hint is shown:
 // - when formatting with `%+v`.
@@ -97,10 +98,12 @@ type ErrorHinter interface {
 
 // WithDetail decorates an error with a textual detail.
 // The detail may contain PII and thus will not reportable.
+// The suggested use case for detail is to augment errors with information
+// useful for debugging.
 //
 // Detail is shown:
 // - when formatting with `%+v`.
-// - with `GetAllHints()` / `FlattenHints()` below.
+// - with `GetAllDetails()` / `FlattenDetails()` below.
 //
 // Note: the detail does not appear in the main error message returned
 // with Error(). Use GetAllDetails() or FlattenDetails() to retrieve

hintdetail_api.go

@@ -27,6 +27,7 @@ type ErrorDetailer = hintdetail.ErrorDetailer
 
 // WithHint decorates an error with a textual hint.
 // The hint may contain PII and thus will not reportable.
+// The suggested use case for hint is to relay information to end users.
 //
 // Hint is shown:
 // - when formatting with `%+v`.
@@ -44,10 +45,12 @@ func WithHintf(err error, format string, args ...interface{}) error {
 
 // WithDetail decorates an error with a textual detail.
 // The detail may contain PII and thus will not reportable.
+// The suggested use case for detail is to augment errors with information
+// useful for debugging.
 //
 // Detail is shown:
 // - when formatting with `%+v`.
-// - with `GetAllHints()` / `FlattenHints()` below.
+// - with `GetAllDetails()` / `FlattenDetails()` below.
 //
 // Note: the detail does not appear in the main error message returned
 // with Error(). Use GetAllDetails() or FlattenDetails() to retrieve