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

@@ -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 {

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 {

config/test-fixtures/validate-output-description/main.tf

@@ -0,0 +1,4 @@
+output "foo" {
+  value       = "5"
+  description = "Number 5"
+}