From 399542a168a230af80167d1ab263cd48b822b21a Mon Sep 17 00:00:00 2001
From: Martin Atkins <mart@degeneration.co.uk>
Date: Fri, 18 Nov 2016 09:09:43 -0800
Subject: [PATCH] core: allow outputs to have descriptions (#9722)

We allow variables to have descriptions specified, as additional context
for a module user as to what should be provided for a given variable.

We previously lacked a similar mechanism for outputs. Since they too are
part of a module's public interface, it makes sense to be able to add
descriptions for these for symmetry's sake.

This change makes a "description" attribute valid within an "output"
configuration block and stores it within the configuration data structure,
but doesn't yet do anything further with it. For now this is useful only
for third-party tools that might parse a module's config to generate
user documentation; later we could expose the descriptions as part of
the "apply" output, but that is left for a separate change.
---
 config/config.go                              | 20 +++++++++++++++----
 config/config_test.go                         | 13 ++++++++++++
 .../validate-output-description/main.tf       |  4 ++++
 3 files changed, 33 insertions(+), 4 deletions(-)
 create mode 100644 config/test-fixtures/validate-output-description/main.tf

diff --git a/config/config.go b/config/config.go
index 439f9d227b..cd11c027d4 100644
--- a/config/config.go
+++ b/config/config.go
@@ -160,10 +160,11 @@ type Variable struct {
 // output marked Sensitive will be output in a masked form following
 // application, but will still be available in state.
 type Output struct {
-	Name      string
-	Sensitive bool
-	DependsOn []string
-	RawConfig *RawConfig
+	Name        string
+	DependsOn   []string
+	Description string
+	Sensitive   bool
+	RawConfig   *RawConfig
 }
 
 // VariableType is the type of value a variable is holding, and returned
@@ -663,6 +664,17 @@ func (c *Config) Validate() error {
 						o.Name))
 					continue
 				}
+				if k == "description" {
+					if desc, ok := o.RawConfig.config[k].(string); ok {
+						o.Description = desc
+						continue
+					}
+
+					errs = append(errs, fmt.Errorf(
+						"%s: value for 'description' must be string",
+						o.Name))
+					continue
+				}
 				invalidKeys = append(invalidKeys, k)
 			}
 			if len(invalidKeys) > 0 {
diff --git a/config/config_test.go b/config/config_test.go
index e89172ff83..f6303e8e73 100644
--- a/config/config_test.go
+++ b/config/config_test.go
@@ -394,6 +394,19 @@ func TestConfigValidate_outputBadField(t *testing.T) {
 	}
 }
 
+func TestConfigValidate_outputDescription(t *testing.T) {
+	c := testConfig(t, "validate-output-description")
+	if err := c.Validate(); err != nil {
+		t.Fatalf("err: %s", err)
+	}
+	if len(c.Outputs) != 1 {
+		t.Fatalf("got %d outputs; want 1", len(c.Outputs))
+	}
+	if got, want := "Number 5", c.Outputs[0].Description; got != want {
+		t.Fatalf("got description %q; want %q", got, want)
+	}
+}
+
 func TestConfigValidate_outputDuplicate(t *testing.T) {
 	c := testConfig(t, "validate-output-dup")
 	if err := c.Validate(); err == nil {
diff --git a/config/test-fixtures/validate-output-description/main.tf b/config/test-fixtures/validate-output-description/main.tf
new file mode 100644
index 0000000000..3f1db8f277
--- /dev/null
+++ b/config/test-fixtures/validate-output-description/main.tf
@@ -0,0 +1,4 @@
+output "foo" {
+  value       = "5"
+  description = "Number 5"
+}