Enhancements for Custom Diagnostic Types Documentation #675
Description
Module version
v1.1.1
Use-cases
In a forum I cannot publicly link to, there was some confusion about the https://developer.hashicorp.com/terraform/plugin/framework/diagnostics#custom-diagnostics-types documentation. In particular, it is not clear that (at least currently) these custom diagnostics must align to the Terraform-understood warning/error severity. Providing a clear use case example would also be helpful there.
Proposal
- Add a sentence talking about the severity constraint (e.g. we don't particularly enable making "hidden from Terraform" diagnostics)
- Add real use case examples (e.g. a error diagnostic type which also stores the underlying error)
// UnderlyingErrorDiagnostic is an error diagnostic
// which also stores the underlying error.
type UnderlyingErrorDiagnostic struct {
Detail string
Summary string
UnderlyingError error
}
func (d UnderlyingErrorDiagnostic) Detail() string {
return d.Detail
}
func (d UnderlyingErrorDiagnostic) Equal(o SpecialDiagnostic) bool {
if d.Detail() != o.Detail() {
return false
}
if d.Summary() != o.Summary() {
return false
}
if d.UnderlyingError == nil {
return o.UnderlyingError == nil
}
if o.UnderlyingError == nil {
return false
}
if d.UnderlyingError.Error() != o.UnderlyingError.Error() {
return false
}
return true
}
func (d UnderlyingErrorDiagnostic) Severity() diag.Severity {
return diag.SeverityError
}
func (d UnderlyingErrorDiagnostic) Summary() string {
return d.Summary
}Another example option may be one that mainly hardcodes summary/detail information except for a particular last bit of information:
type APIErrorDiagnostic struct {
Detail string
}
func (d APIErrorDiagnostic) Detail() string {
return "An unexpected error occurred while calling the API: " + d.Detail
}
func (d APIErrorDiagnostic) Equal(o SpecialDiagnostic) bool {
if d.Detail() != o.Detail() {
return false
}
return true
}
func (d APIErrorDiagnostic) Severity() diag.Severity {
return diag.SeverityError
}
func (d APIErrorDiagnostic) Summary() string {
return "Unexpected API Error"
}