Repository: terraform-docs/terraform-docs
Pull request #466 (2021-04-11 12:16:34)

Feature/lssue461/add description flag
<!--
Thank you for helping to improve terraform-docs!

Please read through https://git.io/JtEzg if this is your first time opening a
terraform-docs pull request. Find us in https://slack.terraform-docs.io/messages/dev if
you need any help contributing.
-->

### Description of your changes

<!--
Briefly describe what this pull request does. Be sure to direct your reviewers'
attention to anything that needs special consideration.

We love pull requests that resolve an open terraform-docs issue. If yours does, you
can uncomment the below line to indicate which issue your PR fixes, for example
"Fixes #500":
-->
- Add `--description` boolean flag that only works when `tfvars hcl` command.
 

feature #461 
<!-- Fixes # -->

I have:

- [x] Read and followed terraform-docs' [contribution process].
- [x] All tests pass when I run `make test`.

### How has this code been tested

<!--
Before reviewers can be confident in the correctness of this pull request, it
needs to tested and shown to be correct. Briefly describe the testing that has
already been done or which is planned for this change.
-->
- Add New Test Pattern  for `trvars hcl` command as `internal/format/testdata/tfvars/hcl-PrintDescription.golden`

[contribution process]: https://git.io/JtEzg



Patch:
diff --git a/cmd/root.go b/cmd/root.go
index a1ef306..d3f665a 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -68,14 +68,8 @@ func NewCommand() *cobra.Command {
 	cmd.PersistentFlags().StringVar(&config.Output.Template, "output-template", cli.OutputTemplate, "Output template")
 
 	cmd.PersistentFlags().BoolVar(&config.Sort.Enabled, "sort", true, "sort items")
-	cmd.PersistentFlags().StringVar(&config.Sort.By, "sort-by", "name", "sort items by criteria ["+cli.SortTypes+"]")
-
-	// deprecated flags ==>
-	cmd.PersistentFlags().BoolVar(&config.Sort.Criteria.Required, "sort-by-required", false, "sort items by name and print required ones first (default false)")
-	cmd.PersistentFlags().BoolVar(&config.Sort.Criteria.Type, "sort-by-type", false, "sort items by type of them (default false)")
-	cmd.PersistentFlags().MarkDeprecated("sort-by-required", "use '--sort-by required' instead") //nolint:errcheck,gosec
-	cmd.PersistentFlags().MarkDeprecated("sort-by-type", "use '--sort-by type' instead")         //nolint:errcheck,gosec
-	// <==
+	cmd.PersistentFlags().BoolVar(&config.Sort.By.Required, "sort-by-required", false, "sort items by name and print required ones first (default false)")
+	cmd.PersistentFlags().BoolVar(&config.Sort.By.Type, "sort-by-type", false, "sort items by type of them (default false)")
 
 	cmd.PersistentFlags().StringVar(&config.HeaderFrom, "header-from", "main.tf", "relative path of a file to read header from")
 	cmd.PersistentFlags().StringVar(&config.FooterFrom, "footer-from", "", "relative path of a file to read footer from (default \"\")")
diff --git a/cmd/tfvars/hcl/hcl.go b/cmd/tfvars/hcl/hcl.go
index 926f5d8..acf2c6b 100644
--- a/cmd/tfvars/hcl/hcl.go
+++ b/cmd/tfvars/hcl/hcl.go
@@ -26,5 +26,6 @@ func NewCommand(config *cli.Config) *cobra.Command {
 		PreRunE:     cli.PreRunEFunc(config),
 		RunE:        cli.RunEFunc(config),
 	}
+	cmd.PersistentFlags().BoolVar(&config.Settings.Description, "description", false, "show Descriptions on variables")
 	return cmd
 }
diff --git a/docs/reference/asciidoc-document.md b/docs/reference/asciidoc-document.md
index 115f262..a1538a3 100644
--- a/docs/reference/asciidoc-document.md
+++ b/docs/reference/asciidoc-document.md
@@ -43,7 +43,8 @@ terraform-docs asciidoc document [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
       --type                        show Type column or section (default true)
 ```
 
diff --git a/docs/reference/asciidoc-table.md b/docs/reference/asciidoc-table.md
index bf66293..f3e40ee 100644
--- a/docs/reference/asciidoc-table.md
+++ b/docs/reference/asciidoc-table.md
@@ -43,7 +43,8 @@ terraform-docs asciidoc table [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
       --type                        show Type column or section (default true)
 ```
 
diff --git a/docs/reference/asciidoc.md b/docs/reference/asciidoc.md
index 0d474c0..97a7e73 100644
--- a/docs/reference/asciidoc.md
+++ b/docs/reference/asciidoc.md
@@ -44,7 +44,8 @@ terraform-docs asciidoc [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Subcommands
diff --git a/docs/reference/json.md b/docs/reference/json.md
index 6f2ba56..0196f74 100644
--- a/docs/reference/json.md
+++ b/docs/reference/json.md
@@ -39,7 +39,8 @@ terraform-docs json [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Example
diff --git a/docs/reference/markdown-document.md b/docs/reference/markdown-document.md
index 61077df..7e748b4 100644
--- a/docs/reference/markdown-document.md
+++ b/docs/reference/markdown-document.md
@@ -44,7 +44,8 @@ terraform-docs markdown document [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
       --type                        show Type column or section (default true)
 ```
 
diff --git a/docs/reference/markdown-table.md b/docs/reference/markdown-table.md
index 0942b29..59cd03f 100644
--- a/docs/reference/markdown-table.md
+++ b/docs/reference/markdown-table.md
@@ -44,7 +44,8 @@ terraform-docs markdown table [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
       --type                        show Type column or section (default true)
 ```
 
diff --git a/docs/reference/markdown.md b/docs/reference/markdown.md
index 37c0745..6907a07 100644
--- a/docs/reference/markdown.md
+++ b/docs/reference/markdown.md
@@ -45,7 +45,8 @@ terraform-docs markdown [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Subcommands
diff --git a/docs/reference/pretty.md b/docs/reference/pretty.md
index aefd9e0..0d6c857 100644
--- a/docs/reference/pretty.md
+++ b/docs/reference/pretty.md
@@ -39,7 +39,8 @@ terraform-docs pretty [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Example
diff --git a/docs/reference/terraform-docs.md b/docs/reference/terraform-docs.md
index 0a607f6..b118cf1 100644
--- a/docs/reference/terraform-docs.md
+++ b/docs/reference/terraform-docs.md
@@ -33,7 +33,8 @@ terraform-docs [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Subcommands
diff --git a/docs/reference/tfvars-hcl.md b/docs/reference/tfvars-hcl.md
index aee4ebc..26236f0 100644
--- a/docs/reference/tfvars-hcl.md
+++ b/docs/reference/tfvars-hcl.md
@@ -19,7 +19,8 @@ terraform-docs tfvars hcl [PATH] [flags]
 ## Options
 
 ```console
-  -h, --help   help for hcl
+      --description   show Descriptions on variables
+  -h, --help          help for hcl
 ```
 
 ## Inherited Options
@@ -38,7 +39,8 @@ terraform-docs tfvars hcl [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Example
diff --git a/docs/reference/tfvars-json.md b/docs/reference/tfvars-json.md
index 9f16a75..448f16e 100644
--- a/docs/reference/tfvars-json.md
+++ b/docs/reference/tfvars-json.md
@@ -38,7 +38,8 @@ terraform-docs tfvars json [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Example
diff --git a/docs/reference/tfvars.md b/docs/reference/tfvars.md
index 26fc0c2..9d6f522 100644
--- a/docs/reference/tfvars.md
+++ b/docs/reference/tfvars.md
@@ -34,7 +34,8 @@ Generate terraform.tfvars of inputs.
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Subcommands
diff --git a/docs/reference/toml.md b/docs/reference/toml.md
index 015edd8..4158500 100644
--- a/docs/reference/toml.md
+++ b/docs/reference/toml.md
@@ -38,7 +38,8 @@ terraform-docs toml [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Example
diff --git a/docs/reference/xml.md b/docs/reference/xml.md
index 8ca1693..8d80162 100644
--- a/docs/reference/xml.md
+++ b/docs/reference/xml.md
@@ -38,7 +38,8 @@ terraform-docs xml [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Example
diff --git a/docs/reference/yaml.md b/docs/reference/yaml.md
index 11a4d5f..6fe7be9 100644
--- a/docs/reference/yaml.md
+++ b/docs/reference/yaml.md
@@ -38,7 +38,8 @@ terraform-docs yaml [PATH] [flags]
       --show strings                show section [footer, header, inputs, modules, outputs, providers, requirements, resources]
       --show-all                    show all sections (default true)
       --sort                        sort items (default true)
-      --sort-by string              sort items by criteria [name, required, type] (default "name")
+      --sort-by-required            sort items by name and print required ones first (default false)
+      --sort-by-type                sort items by type of them (default false)
 ```
 
 ## Example
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index 6b14527..73bddaf 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -68,7 +68,9 @@ output-values:
 
 sort:
   enabled: true
-  by: name
+  by:
+    - required
+    - type
 
 settings:
   anchor: true
@@ -87,6 +89,7 @@ settings:
 - `sections.hide-all` and `sections.show-all`
 - `sections.hide-all` and `sections.hide`
 - `sections.show-all` and `sections.show`
+- `sort.by.required` and `sort.by.type`
 
 ## Formatters
 
@@ -196,14 +199,3 @@ output:
     
     {{ .Content }}
 ```
-
-## Sort
-
-To enable sorting of elements `sort.enabled` (or `--sort bool` CLI flag) can be
-used. This will indicate sorting is enabled or not, but consecutively type of
-sorting can also be specified with `sort.by` (or `--sort-by string` CLI flag).
-The following sort types are supported:
-
-- `name` (default): name of items
-- `required`: by name of inputs AND show required ones first
-- `type`: type of inputs
diff --git a/examples/.terraform-docs.yml b/examples/.terraform-docs.yml
index 6c71a18..f3ff1f3 100644
--- a/examples/.terraform-docs.yml
+++ b/examples/.terraform-docs.yml
@@ -27,7 +27,8 @@ sections:
 
 sort:
   enabled: true
-  by: required
+  by:
+    - required
 
 settings:
   indent: 4
diff --git a/internal/cli/config.go b/internal/cli/config.go
index e9e0699..41e740f 100644
--- a/internal/cli/config.go
+++ b/internal/cli/config.go
@@ -29,16 +29,7 @@ const (
 	sectionResources    = "resources"
 )
 
-var allSections = []string{
-	sectionFooter,
-	sectionHeader,
-	sectionInputs,
-	sectionModules,
-	sectionOutputs,
-	sectionProviders,
-	sectionRequirements,
-	sectionResources,
-}
+var allSections = []string{sectionFooter, sectionHeader, sectionInputs, sectionModules, sectionOutputs, sectionProviders, sectionRequirements, sectionResources}
 
 // AllSections list.
 var AllSections = strings.Join(allSections, ", ")
@@ -234,38 +225,21 @@ func (o *outputvalues) validate() error {
 	return nil
 }
 
-const (
-	sortName     = "name"
-	sortRequired = "required"
-	sortType     = "type"
-)
-
-var allSorts = []string{
-	sortName,
-	sortRequired,
-	sortType,
-}
-
-// SortTypes list.
-var SortTypes = strings.Join(allSorts, ", ")
-
 type sortby struct {
-	Name     bool `name:"name"`
 	Required bool `name:"required"`
 	Type     bool `name:"type"`
 }
 type sort struct {
-	Enabled  bool   `yaml:"enabled"`
-	By       string `yaml:"by"`
-	Criteria sortby `yaml:"-"`
+	Enabled bool     `yaml:"enabled"`
+	ByList  []string `yaml:"by"`
+	By      sortby   `yaml:"-"`
 }
 
 func defaultSort() sort {
 	return sort{
 		Enabled: true,
-		By:      sortName,
-		Criteria: sortby{
-			Name:     true,
+		ByList:  []string{},
+		By: sortby{
 			Required: false,
 			Type:     false,
 		},
@@ -273,43 +247,43 @@ func defaultSort() sort {
 }
 
 func (s *sort) validate() error {
-	found := false
-	for _, item := range allSorts {
-		if item == s.By {
-			found = true
-			break
+	types := []string{"required", "type"}
+	for _, item := range s.ByList {
+		switch item {
+		case types[0], types[1]:
+		default:
+			return fmt.Errorf("'%s' is not a valid sort type", item)
 		}
 	}
-	if !found {
-		return fmt.Errorf("'%s' is not a valid sort type", s.By)
-	}
-	if s.Criteria.Required && s.Criteria.Type {
+	if s.By.Required && s.By.Type {
 		return fmt.Errorf("'--sort-by-required' and '--sort-by-type' can't be used together")
 	}
 	return nil
 }
 
 type settings struct {
-	Anchor    bool `yaml:"anchor"`
-	Color     bool `yaml:"color"`
-	Default   bool `yaml:"default"`
-	Escape    bool `yaml:"escape"`
-	Indent    int  `yaml:"indent"`
-	Required  bool `yaml:"required"`
-	Sensitive bool `yaml:"sensitive"`
-	Type      bool `yaml:"type"`
+	Anchor      bool `yaml:"anchor"`
+	Color       bool `yaml:"color"`
+	Default     bool `yaml:"default"`
+	Escape      bool `yaml:"escape"`
+	Indent      int  `yaml:"indent"`
+	Required    bool `yaml:"required"`
+	Sensitive   bool `yaml:"sensitive"`
+	Type        bool `yaml:"type"`
+	Description bool `yaml:"description"`
 }
 
 func defaultSettings() settings {
 	return settings{
-		Anchor:    true,
-		Color:     true,
-		Default:   true,
-		Escape:    true,
-		Indent:    2,
-		Required:  true,
-		Sensitive: true,
-		Type:      true,
+		Anchor:      true,
+		Color:       true,
+		Default:     true,
+		Escape:      true,
+		Indent:      2,
+		Required:    true,
+		Sensitive:   true,
+		Type:        true,
+		Description: false,
 	}
 }
 
@@ -371,11 +345,6 @@ func (c *Config) process() {
 	if c.FooterFrom == "" && !changedfs["footer-from"] {
 		c.Sections.footer = false
 	}
-
-	// Enable specified sort criteria
-	c.Sort.Criteria.Name = c.Sort.Enabled && c.Sort.By == sortName
-	c.Sort.Criteria.Required = c.Sort.Enabled && c.Sort.By == sortRequired
-	c.Sort.Criteria.Type = c.Sort.Enabled && c.Sort.By == sortType
 }
 
 // validate config and check for any misuse or misconfiguration
@@ -460,14 +429,15 @@ func (c *Config) extract() (*print.Settings, *terraform.Options) {
 	options.OutputValuesPath = c.OutputValues.From
 
 	// sort
-	options.SortBy.Name = c.Sort.Enabled && c.Sort.Criteria.Name
-	options.SortBy.Required = c.Sort.Enabled && c.Sort.Criteria.Required
-	options.SortBy.Type = c.Sort.Enabled && c.Sort.Criteria.Type
+	options.SortBy.Name = c.Sort.Enabled
+	options.SortBy.Required = c.Sort.Enabled && c.Sort.By.Required
+	options.SortBy.Type = c.Sort.Enabled && c.Sort.By.Type
 
 	// settings
 	settings.EscapeCharacters = c.Settings.Escape
 	settings.IndentLevel = c.Settings.Indent
 	settings.ShowAnchor = c.Settings.Anchor
+	settings.ShowDescription = c.Settings.Description
 	settings.ShowColor = c.Settings.Color
 	settings.ShowDefault = c.Settings.Default
 	settings.ShowRequired = c.Settings.Required
diff --git a/internal/cli/reader.go b/internal/cli/reader.go
index 39e48ca..eaef086 100644
--- a/internal/cli/reader.go
+++ b/internal/cli/reader.go
@@ -75,14 +75,23 @@ func (c *cfgreader) parse() error { //nolint:gocyclo
 			c.overrideShow()
 		case "hide":
 			c.overrideHide()
-		case "sort", "sort-by":
-			mapping := map[string]string{"sort": "enabled", "sort-by": "by"}
-			if err := c.overrideValue(mapping[flag], &c.config.Sort, &c.overrides.Sort); err != nil {
+		case "sort":
+			if err := c.overrideValue("enabled", &c.config.Sort, &c.overrides.Sort); err != nil {
 				return err
 			}
 		case "sort-by-required", "sort-by-type":
 			mapping := map[string]string{"sort-by-required": "required", "sort-by-type": "type"}
-			c.config.Sort.By = mapping[flag]
+			if !contains(c.config.Sort.ByList, mapping[flag]) {
+				c.config.Sort.ByList = append(c.config.Sort.ByList, mapping[flag])
+			}
+			el := reflect.ValueOf(&c.overrides.Sort.By).Elem()
+			field, err := c.findField(el, "name", mapping[flag])
+			if err != nil {
+				return err
+			}
+			if !el.FieldByName(field).Bool() {
+				c.config.Sort.ByList = remove(c.config.Sort.ByList, mapping[flag])
+			}
 		case "output-file", "output-mode", "output-template":
 			mapping := map[string]string{"output-file": "file", "output-mode": "mode", "output-template": "template"}
 			if err := c.overrideValue(mapping[flag], &c.config.Output, &c.overrides.Output); err != nil {
@@ -100,6 +109,10 @@ func (c *cfgreader) parse() error { //nolint:gocyclo
 		}
 	}
 
+	if err := c.updateSortTypes(); err != nil {
+		return err
+	}
+
 	return nil
 }
 
@@ -147,6 +160,18 @@ func (c *cfgreader) overrideHide() {
 	}
 }
 
+func (c *cfgreader) updateSortTypes() error {
+	for _, item := range c.config.Sort.ByList {
+		el := reflect.ValueOf(&c.config.Sort.By).Elem()
+		field, err := c.findField(el, "name", item)
+		if err != nil {
+			return err
+		}
+		el.FieldByName(field).Set(reflect.ValueOf(true))
+	}
+	return nil
+}
+
 func (c *cfgreader) findField(el reflect.Value, tag string, value string) (string, error) {
 	for i := 0; i < el.NumField(); i++ {
 		f := el.Type().Field(i)
diff --git a/internal/format/templates/tfvars_hcl.tmpl b/internal/format/templates/tfvars_hcl.tmpl
index 7c35573..35ab310 100644
--- a/internal/format/templates/tfvars_hcl.tmpl
+++ b/internal/format/templates/tfvars_hcl.tmpl
@@ -1,5 +1,11 @@
 {{- if .Module.Inputs -}}
     {{- range $i, $k := .Module.Inputs -}}
+      {{ if and $k.Description showDescription -}} 
+          {{ convertToComment $k.Description }}
+          {{ align $k.Name $i }} = {{ value $k.GetValue }}
+
+      {{ else -}}
         {{ align $k.Name $i }} = {{ value $k.GetValue }}
+      {{ end -}}
     {{ end -}}
-{{- end -}}
\ No newline at end of file
+{{- end -}}
diff --git a/internal/format/tfvars_hcl.go b/internal/format/tfvars_hcl.go
index f2eb10f..2d044d6 100644
--- a/internal/format/tfvars_hcl.go
+++ b/internal/format/tfvars_hcl.go
@@ -1,6 +1,5 @@
 /*
 Copyright 2021 The terraform-docs Authors.
-
 Licensed under the MIT license (the "License"); you may not
 use this file except in compliance with the License.
 
@@ -20,6 +19,7 @@ import (
 	"github.com/terraform-docs/terraform-docs/internal/print"
 	"github.com/terraform-docs/terraform-docs/internal/template"
 	"github.com/terraform-docs/terraform-docs/internal/terraform"
+	"github.com/terraform-docs/terraform-docs/internal/types"
 )
 
 //go:embed templates/tfvars_hcl.tmpl
@@ -48,6 +48,12 @@ func NewTfvarsHCL(settings *print.Settings) print.Engine {
 			}
 			return s
 		},
+		"convertToComment": func(s types.String) string {
+			return "\n# " + strings.ReplaceAll(string(s), "\n", "\n# ")
+		},
+		"showDescription": func() bool {
+			return settings.ShowDescription
+		},
 	})
 	return &TfvarsHCL{
 		template: tt,
@@ -56,7 +62,7 @@ func NewTfvarsHCL(settings *print.Settings) print.Engine {
 
 // Print a Terraform module as Terraform tfvars HCL.
 func (h *TfvarsHCL) Print(module *terraform.Module, settings *print.Settings) (string, error) {
-	alignments(module.Inputs)
+	alignments(module.Inputs, settings)
 	rendered, err := h.template.Render(module)
 	if err != nil {
 		return "", err
@@ -64,15 +70,20 @@ func (h *TfvarsHCL) Print(module *terraform.Module, settings *print.Settings) (s
 	return strings.TrimSuffix(sanitize(rendered), "\n"), nil
 }
 
-func alignments(inputs []*terraform.Input) {
+func isMultilineFormat(input *terraform.Input) bool {
+	isList := input.Type == "list" || reflect.TypeOf(input.Default).Name() == "List"
+	isMap := input.Type == "map" || reflect.TypeOf(input.Default).Name() == "Map"
+	return (isList || isMap) && input.Default.Length() > 0
+}
+
+func alignments(inputs []*terraform.Input, settings *print.Settings) {
 	padding = make([]int, len(inputs))
 	maxlen := 0
 	index := 0
 	for i, input := range inputs {
-		isList := input.Type == "list" || reflect.TypeOf(input.Default).Name() == "List"
-		isMap := input.Type == "map" || reflect.TypeOf(input.Default).Name() == "Map"
+		isDescribed := settings.ShowDescription && input.Description.Length() > 0
 		l := len(input.Name)
-		if (isList || isMap) && input.Default.Length() > 0 {
+		if isMultilineFormat(input) || isDescribed {
 			for j := index; j < i; j++ {
 				padding[j] = maxlen
 			}
diff --git a/internal/print/settings.go b/internal/print/settings.go
index b6fd9b3..8f533aa 100644
--- a/internal/print/settings.go
+++ b/internal/print/settings.go
@@ -46,6 +46,12 @@ type Settings struct {
 	// scope: Pretty
 	ShowColor bool
 
+	// ShowDescription show "Descriptions on variables" column
+	//
+	// default: false
+	// scope: tfvars hcl
+	ShowDescription bool
+
 	// ShowDefault show "Default" column
 	//
 	// default: true
@@ -128,6 +134,7 @@ func DefaultSettings() *Settings {
 		ShowAnchor:       true,
 		ShowColor:        true,
 		ShowDefault:      true,
+		ShowDescription:  false,
 		ShowFooter:       false,
 		ShowHeader:       true,
 		ShowInputs:       true,


Test patch:
diff --git a/internal/cli/reader_test.go b/internal/cli/reader_test.go
index 8d6c013..98ddd17 100644
--- a/internal/cli/reader_test.go
+++ b/internal/cli/reader_test.go
@@ -318,6 +318,62 @@ func TestOverrideHide(t *testing.T) {
 	}
 }
 
+func TestUpdateSortTypes(t *testing.T) {
+	tests := []struct {
+		name       string
+		appendFn   func(config *Config)
+		expectedFn func(config *Config) bool
+		wantErr    bool
+		errMsg     string
+	}{
+		{
+			name:       "override values of given field",
+			appendFn:   func(config *Config) { config.Sort.ByList = append(config.Sort.ByList, "required") },
+			expectedFn: func(config *Config) bool { return config.Sort.By.Required },
+			wantErr:    false,
+			errMsg:     "",
+		},
+		{
+			name:       "override values of given field",
+			appendFn:   func(config *Config) { config.Sort.ByList = append(config.Sort.ByList, "type") },
+			expectedFn: func(config *Config) bool { return config.Sort.By.Type },
+			wantErr:    false,
+			errMsg:     "",
+		},
+		{
+			name:       "override values of given field",
+			appendFn:   func(config *Config) { config.Sort.ByList = append(config.Sort.ByList, "unknown") },
+			expectedFn: func(config *Config) bool { return false },
+			wantErr:    true,
+			errMsg:     "field with tag: 'name', value; 'unknown' not found or not readable",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert := assert.New(t)
+			config := DefaultConfig()
+			c := cfgreader{config: config}
+
+			tt.appendFn(config)
+
+			// make sure before values is false
+			assert.Equal(false, tt.expectedFn(config))
+
+			// then update sort types
+			err := c.updateSortTypes()
+
+			if tt.wantErr {
+				assert.NotNil(err)
+				assert.Equal(tt.errMsg, err.Error())
+			} else {
+				// then make sure values is true
+				assert.Nil(err)
+				assert.Equal(true, tt.expectedFn(config))
+			}
+		})
+	}
+}
+
 func TestFindField(t *testing.T) {
 	type sample struct {
 		A string `foo:"a"`
diff --git a/internal/format/testdata/tfvars/hcl-PrintDescription.golden b/internal/format/testdata/tfvars/hcl-PrintDescription.golden
new file mode 100644
index 0000000..941003c
--- /dev/null
+++ b/internal/format/testdata/tfvars/hcl-PrintDescription.golden
@@ -0,0 +1,104 @@
+
+# A variable with underscores.
+input_with_underscores = ""
+
+# It's list number two.
+list-2 = ""
+
+# It's map number two.
+map-2 = ""
+
+# It's number number two.
+number-2 = ""
+
+# It's string number two.
+string-2 = ""
+
+string_no_default = ""
+unquoted          = ""
+
+# It's bool number one.
+bool-1 = true
+
+# It's bool number two.
+bool-2 = false
+
+bool-3             = true
+bool_default_false = false
+
+# This is a complicated one. We need a newline.  
+# And an example in a code block
+# ```
+# default     = [
+#   "machine rack01:neptune"
+# ]
+# ```
+#
+input-with-code-block = [
+  "name rack:location"
+]
+
+# It includes v1 | v2 | v3
+input-with-pipe = "v1"
+
+# It's list number one.
+list-1 = [
+  "a",
+  "b",
+  "c"
+]
+
+list-3             = []
+list_default_empty = []
+
+# This description is itself markdown.
+#
+# It spans over multiple lines.
+#
+long_type = {
+  "bar": {
+    "bar": "bar",
+    "foo": "bar"
+  },
+  "buzz": [
+    "fizz",
+    "buzz"
+  ],
+  "fizz": [],
+  "foo": {
+    "bar": "foo",
+    "foo": "foo"
+  },
+  "name": "hello"
+}
+
+# It's map number one.
+map-1 = {
+  "a": 1,
+  "b": 2,
+  "c": 3
+}
+
+map-3 = {}
+
+# The description contains `something_with_underscore`. Defaults to 'VALUE_WITH_UNDERSCORE'.
+no-escape-default-value = "VALUE_WITH_UNDERSCORE"
+
+# It's number number one.
+number-1 = 42
+
+number-3             = "19"
+number-4             = 15.75
+number_default_zero  = 0
+object_default_empty = {}
+
+# It's string number one.
+string-1 = "bar"
+
+string-3             = ""
+string-special-chars = "\\.<>[]{}_-"
+string_default_empty = ""
+string_default_null  = ""
+
+# The description contains url. https://www.domain.com/foo/bar_baz.html
+with-url = ""
\ No newline at end of file
diff --git a/internal/format/tfvars_hcl_test.go b/internal/format/tfvars_hcl_test.go
index 975951f..156d3f1 100644
--- a/internal/format/tfvars_hcl_test.go
+++ b/internal/format/tfvars_hcl_test.go
@@ -42,6 +42,19 @@ func TestTfvarsHcl(t *testing.T) {
 			settings: print.Settings{EscapeCharacters: true},
 			options:  terraform.Options{},
 		},
+		"PrintDescription": {
+			settings: testutil.WithSections(
+				print.Settings{
+					ShowDescription: true,
+				},
+			),
+			options: terraform.Options{
+				SortBy: &terraform.SortBy{
+					Name:     true,
+					Required: true,
+				},
+			},
+		},
 		"SortByName": {
 			settings: testutil.WithSections(),
 			options: terraform.Options{