From 4ce1c7d20218c56ac655ce201424029c2b51dae9 Mon Sep 17 00:00:00 2001
From: Alex Pilon <apilon@hashicorp.com>
Date: Mon, 13 Apr 2020 19:49:04 -0400
Subject: [PATCH] godoc comments for new Diagnostic types

---
 diag/diagnostic.go | 56 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 4 deletions(-)

diff --git a/diag/diagnostic.go b/diag/diagnostic.go
index 156d1150af6..c6688aabbd8 100644
--- a/diag/diagnostic.go
+++ b/diag/diagnostic.go
@@ -7,8 +7,19 @@ import (
 	"github.com/zclconf/go-cty/cty"
 )
 
+// Diagnostics is a collection of Diagnostic.
+//
+// Developers should append and build the list of diagnostics up until a fatal
+// error is reached, at which point they should return the Diagnostics to the
+// SDK.
 type Diagnostics []Diagnostic
 
+// HasError returns true is Diagnostics contains an instance of
+// Severity == Error.
+//
+// This helper aims to mimic the go error practices of if err != nil. After any
+// operation that returns Diagnostics, check that it HasError and bubble up the
+// stack.
 func (diags Diagnostics) HasError() bool {
 	for i := range diags {
 		if diags[i].Severity == Error {
@@ -18,13 +29,44 @@ func (diags Diagnostics) HasError() bool {
 	return false
 }
 
+// Diagnostic is a contextual message intended at outlining problems in user
+// configuration.
+//
+// It supports multiple levels of severity (Error or Warning), a short Summary
+// of the problem, an optional longer Detail message that can assist the user in
+// fixing the problem, as well as an AttributePath representation which
+// Terraform uses to indicate where the issue took place in the user's
+// configuration.
+//
+// A Diagnostic will typically be used to pinpoint a problem with user
+// configuration, however it can still be used to present warnings or errors
+// to the user without any AttributePath set.
 type Diagnostic struct {
-	Severity      Severity
-	Summary       string
-	Detail        string
+	// Severity indicates the level of the Diagnostic. Currently can be set to
+	// either Error or Warning
+	Severity Severity
+	// Summary is a short description of the problem, rendered above location
+	// information
+	Summary string
+	// Detail is an optional second message rendered below location information
+	// typically used to communicate a potential fix to the user.
+	Detail string
+	// AttributePath is a representation of the path starting from the root of
+	// block (resource, datasource, provider) under evaluation by the SDK, to
+	// the attribute that the Diagnostic should be associated to.
+	//
+	// It is represented with cty.Path, the SDK currently only supports path
+	// steps of either cty.GetAttrStep (an actual attribute) or cty.IndexStep
+	// (a step with Key of cty.StringVal for map indexes, and cty.NumberVal
+	// list indexes, pathing into sets is not currently supported). Please see
+	// go-cty documentation for more information.
+	//
+	// Terraform will use this information to render information on where the
+	// problem took place in the user's configuration.
 	AttributePath cty.Path
 }
 
+// Validate ensures a valid Severity and a non-empty Summary are set.
 func (d Diagnostic) Validate() error {
 	var validSev bool
 	for _, sev := range severities {
@@ -37,11 +79,12 @@ func (d Diagnostic) Validate() error {
 		return fmt.Errorf("invalid severity: %v", d.Severity)
 	}
 	if d.Summary == "" {
-		return errors.New("empty detail")
+		return errors.New("empty summary")
 	}
 	return nil
 }
 
+// FromErr will convert an error into a Diagnostic
 func FromErr(err error) Diagnostic {
 	return Diagnostic{
 		Severity: Error,
@@ -49,6 +92,11 @@ func FromErr(err error) Diagnostic {
 	}
 }
 
+// Severity is an enum type marking the severity level of a Diagnostic
+//
+// Valid levels are
+// - Error
+// - Warning
 type Severity int
 
 const (