From ab2a92dd84aa4d0e12e7a6ef929aee765dd2aa8d Mon Sep 17 00:00:00 2001 From: Michael Pratt Date: Wed, 7 May 2025 14:00:37 -0400 Subject: [PATCH] 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 LUCI-TryBot-Result: Go LUCI Auto-Submit: Michael Pratt --- src/runtime/error.go | 16 +++++++++++++--- 1 file 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() } -- 2.51.0