runtime: improve Error documentation

The current Error documentation is vacuous and doesn't say anything
about what this interface is actually for. Expand to include its meaning
and why it might be used.

Change-Id: I6a6a636cbd5f5788cb9d1a88845de16b98f7424b
Reviewed-on: https://go-review.googlesource.com/c/go/+/670635
Reviewed-by: Cherry Mui <cherryyz@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Michael Pratt <mpratt@google.com>

1 files changed, 13 insertions, 3 deletions

diff --git a/src/runtime/error.go b/src/runtime/error.go
index 9017c0436c..8e50c0fea4 100644
--- a/src/runtime/error.go
+++ b/src/runtime/error.go
@@ -10,14 +10,24 @@ import (
 	"internal/runtime/sys"
 )
 
-// The Error interface identifies a run time error.
+// Error identifies a runtime error used in panic.
+//
+// The Go runtime triggers panics for a variety of cases, as described by the
+// Go Language Spec, such as out-of-bounds slice/array access, close of nil
+// channels, type assertion failures, etc.
+//
+// When these cases occur, the Go runtime panics with an error that implements
+// Error. This can be useful when recovering from panics to distinguish between
+// custom application panics and fundamental runtime panics.
+//
+// Packages outside of the Go standard library should not implement Error.
 type Error interface {
 	error
 
 	// RuntimeError is a no-op function but
-	// serves to distinguish types that are run time
+	// serves to distinguish types that are runtime
 	// errors from ordinary errors: a type is a
-	// run time error if it has a RuntimeError method.
+	// runtime error if it has a RuntimeError method.
 	RuntimeError()
 }