]> Cypherpunks repositories - gostls13.git/commitdiff
runtime: improve Error documentation
authorMichael Pratt <mpratt@google.com>
Wed, 7 May 2025 18:00:37 +0000 (14:00 -0400)
committerGopher Robot <gobot@golang.org>
Wed, 7 May 2025 18:33:45 +0000 (11:33 -0700)
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>

src/runtime/error.go

index 9017c0436c88c07474d22ca9a7870cd759c65a60..8e50c0fea4cb293883839937dffa3f4d5eb490d3 100644 (file)
@@ -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()
 }