Map new proto fields

Borrows some core code from 23acb02cb846fd002e7a0b52904ee88019b33211

Author: paultyng

helper/schema/core_schema.go

@@ -7,6 +7,26 @@ import (
 	"github.com/zclconf/go-cty/cty"
 )
 
+var (
+	// DescriptionKind is the default StringKind of descriptions in this provider.
+	// It defaults to StringPlain but can be globally switched to StringMarkdown.
+	DescriptionKind = configschema.StringPlain
+
+	// SchemaDescriptionBuilder converts helper/schema.Schema Descriptions to configschema.Attribute
+	// and Block Descriptions. This method can be used to modify the description text prior to it
+	// being returned in the schema.
+	SchemaDescriptionBuilder = func(s *Schema) string {
+		return s.Description
+	}
+
+	// ResourceDescriptionBuilder converts helper/schema.Resource Descriptions to configschema.Block
+	// Descriptions at the resource top level. This method can be used to modify the description prior
+	// to it being returned in the schema.
+	ResourceDescriptionBuilder = func(r *Resource) string {
+		return r.Description
+	}
+)
+
 // The functions and methods in this file are concerned with the conversion
 // of this package's schema model into the slightly-lower-level schema model
 // used by Terraform core for configuration parsing.
@@ -115,13 +135,22 @@ func (s *Schema) coreConfigSchemaAttribute() *configschema.Attribute {
 		}
 	}
 
+	desc := SchemaDescriptionBuilder(s)
+	descKind := DescriptionKind
+	if desc == "" {
+		// fallback to plain text if empty
+		descKind = configschema.StringPlain
+	}
+
 	return &configschema.Attribute{
-		Type:        s.coreConfigSchemaType(),
-		Optional:    opt,
-		Required:    reqd,
-		Computed:    s.Computed,
-		Sensitive:   s.Sensitive,
-		Description: s.Description,
+		Type:            s.coreConfigSchemaType(),
+		Optional:        opt,
+		Required:        reqd,
+		Computed:        s.Computed,
+		Sensitive:       s.Sensitive,
+		Description:     desc,
+		DescriptionKind: descKind,
+		Deprecated:      s.Deprecated != "",
 	}
 }
 
@@ -132,6 +161,17 @@ func (s *Schema) coreConfigSchemaBlock() *configschema.NestedBlock {
 	ret := &configschema.NestedBlock{}
 	if nested := s.Elem.(*Resource).coreConfigSchema(); nested != nil {
 		ret.Block = *nested
+
+		desc := SchemaDescriptionBuilder(s)
+		descKind := DescriptionKind
+		if desc == "" {
+			// fallback to plain text if empty
+			descKind = configschema.StringPlain
+		}
+		// set these on the block from the attribute Schema
+		ret.Block.Description = desc
+		ret.Block.DescriptionKind = descKind
+		ret.Block.Deprecated = s.Deprecated != ""
 	}
 	switch s.Type {
 	case TypeList:
@@ -231,6 +271,18 @@ func (s *Schema) coreConfigSchemaType() cty.Type {
 func (r *Resource) CoreConfigSchema() *configschema.Block {
 	block := r.coreConfigSchema()
 
+	desc := ResourceDescriptionBuilder(r)
+	descKind := DescriptionKind
+	if desc == "" {
+		// fallback to plain text if empty
+		descKind = configschema.StringPlain
+	}
+
+	// Only apply Resource Description, Kind, Deprecation at top level
+	block.Description = desc
+	block.DescriptionKind = descKind
+	block.Deprecated = r.DeprecationMessage != ""
+
 	if block.Attributes == nil {
 		block.Attributes = map[string]*configschema.Attribute{}
 	}

helper/schema/core_schema_test.go

@@ -31,6 +31,15 @@ func testResource(block *configschema.Block) *configschema.Block {
 }
 
 func TestSchemaMapCoreConfigSchema(t *testing.T) {
+	// these are global so if new tests are written we should probably employ a mutex
+	DescriptionKind = configschema.StringMarkdown
+	SchemaDescriptionBuilder = func(s *Schema) string {
+		if s.Required && s.Description != "" {
+			return fmt.Sprintf("**Required** %s", s.Description)
+		}
+		return s.Description
+	}
+
 	tests := map[string]struct {
 		Schema map[string]*Schema
 		Want   *configschema.Block
@@ -63,9 +72,10 @@ func TestSchemaMapCoreConfigSchema(t *testing.T) {
 			testResource(&configschema.Block{
 				Attributes: map[string]*configschema.Attribute{
 					"int": {
-						Type:        cty.Number,
-						Required:    true,
-						Description: "foo bar baz",
+						Type:            cty.Number,
+						Required:        true,
+						Description:     "**Required** foo bar baz",
+						DescriptionKind: configschema.StringMarkdown,
 					},
 					"float": {
 						Type:     cty.Number,

helper/schema/resource.go

@@ -172,6 +172,11 @@ type Resource struct {
 	// actions (Create, Read, Update, Delete, Default) to the Resource struct, and
 	// accessing them in the matching methods.
 	Timeouts *ResourceTimeout
+
+	// Description is used as the description for docs, the language server and
+	// other user facing usage. It can be plain-text or markdown depending on the
+	// global DescriptionKind setting.
+	Description string
 }
 
 // ShimInstanceStateFromValue converts a cty.Value to a

helper/schema/schema.go

@@ -138,9 +138,9 @@ type Schema struct {
 	Default     interface{}
 	DefaultFunc SchemaDefaultFunc
 
-	// Description is used as the description for docs or asking for user
-	// input. It should be relatively short (a few sentences max) and should
-	// be formatted to fit a CLI.
+	// Description is used as the description for docs, the language server and
+	// other user facing usage. It can be plain-text or markdown depending on the
+	// global DescriptionKind setting.
 	Description string
 
 	// InputDefault is the default value to use for when inputs are requested.

internal/configs/configschema/schema.go

@@ -4,6 +4,17 @@ import (
 	"github.com/zclconf/go-cty/cty"
 )
 
+// StringKind represents the format a string is in.
+type StringKind int
+
+const (
+	// StringPlain indicates a string is plain-text and requires no processing for display.
+	StringPlain StringKind = iota
+	// StringMarkdown indicates a string is in markdown format and may
+	// require additional processing to display.
+	StringMarkdown
+)
+
 // Block represents a configuration block.
 //
 // "Block" here is a logical grouping construct, though it happens to map
@@ -21,6 +32,15 @@ type Block struct {
 	// BlockTypes describes any nested block types that may appear directly
 	// inside the block.
 	BlockTypes map[string]*NestedBlock
+
+	// Description and DescriptionKind contain a user facing description of the block
+	// and the format of that string.
+	Description     string
+	DescriptionKind StringKind
+
+	// Deprecated indicates whether the block has been marked as deprecated in the
+	// provider and usage should be discouraged.
+	Deprecated bool
 }
 
 // Attribute represents a configuration attribute, within a block.
@@ -32,7 +52,8 @@ type Attribute struct {
 	// usage of the attribute. A description should be concise and use only
 	// one or two sentences, leaving full definition to longer-form
 	// documentation defined elsewhere.
-	Description string
+	Description     string
+	DescriptionKind StringKind
 
 	// Required, if set to true, specifies that an omitted or null value is
 	// not permitted.
@@ -55,6 +76,10 @@ type Attribute struct {
 	// future to help Terraform mask sensitive information. (Terraform
 	// currently achieves this in a limited sense via other mechanisms.)
 	Sensitive bool
+
+	// Deprecated indicates whether the attribute has been marked as deprecated in the
+	// provider and usage should be discouraged.
+	Deprecated bool
 }
 
 // NestedBlock represents the embedding of one block within another.

internal/plugin/convert/schema.go

@@ -13,17 +13,24 @@ import (
 // ConfigSchemaToProto takes a *configschema.Block and converts it to a
 // proto.Schema_Block for a grpc response.
 func ConfigSchemaToProto(b *configschema.Block) *proto.Schema_Block {
-	block := &proto.Schema_Block{}
+	block := &proto.Schema_Block{
+		Description:     b.Description,
+		DescriptionKind: protoStringKind(b.DescriptionKind),
+		Deprecated:      b.Deprecated,
+	}
 
 	for _, name := range sortedKeys(b.Attributes) {
 		a := b.Attributes[name]
+
 		attr := &proto.Schema_Attribute{
-			Name:        name,
-			Description: a.Description,
-			Optional:    a.Optional,
-			Computed:    a.Computed,
-			Required:    a.Required,
-			Sensitive:   a.Sensitive,
+			Name:            name,
+			Description:     a.Description,
+			DescriptionKind: protoStringKind(a.DescriptionKind),
+			Optional:        a.Optional,
+			Computed:        a.Computed,
+			Required:        a.Required,
+			Sensitive:       a.Sensitive,
+			Deprecated:      a.Deprecated,
 		}
 
 		ty, err := json.Marshal(a.Type)
@@ -44,6 +51,15 @@ func ConfigSchemaToProto(b *configschema.Block) *proto.Schema_Block {
 	return block
 }
 
+func protoStringKind(k configschema.StringKind) proto.StringKind {
+	switch k {
+	default:
+		return proto.StringKind_PLAIN
+	case configschema.StringMarkdown:
+		return proto.StringKind_MARKDOWN
+	}
+}
+
 func protoSchemaNestedBlock(name string, b *configschema.NestedBlock) *proto.Schema_NestedBlock {
 	var nesting proto.Schema_NestedBlock_NestingMode
 	switch b.Nesting {
@@ -83,15 +99,21 @@ func ProtoToConfigSchema(b *proto.Schema_Block) *configschema.Block {
 	block := &configschema.Block{
 		Attributes: make(map[string]*configschema.Attribute),
 		BlockTypes: make(map[string]*configschema.NestedBlock),
+
+		Description:     b.Description,
+		DescriptionKind: schemaStringKind(b.DescriptionKind),
+		Deprecated:      b.Deprecated,
 	}
 
 	for _, a := range b.Attributes {
 		attr := &configschema.Attribute{
-			Description: a.Description,
-			Required:    a.Required,
-			Optional:    a.Optional,
-			Computed:    a.Computed,
-			Sensitive:   a.Sensitive,
+			Description:     a.Description,
+			DescriptionKind: schemaStringKind(a.DescriptionKind),
+			Required:        a.Required,
+			Optional:        a.Optional,
+			Computed:        a.Computed,
+			Sensitive:       a.Sensitive,
+			Deprecated:      a.Deprecated,
 		}
 
 		if err := json.Unmarshal(a.Type, &attr.Type); err != nil {
@@ -108,6 +130,15 @@ func ProtoToConfigSchema(b *proto.Schema_Block) *configschema.Block {
 	return block
 }
 
+func schemaStringKind(k proto.StringKind) configschema.StringKind {
+	switch k {
+	default:
+		return configschema.StringPlain
+	case proto.StringKind_MARKDOWN:
+		return configschema.StringMarkdown
+	}
+}
+
 func schemaNestedBlock(b *proto.Schema_NestedBlock) *configschema.NestedBlock {
 	var nesting configschema.NestingMode
 	switch b.Nesting {