feat: Add new flag 'read-comments' to optionally process comments as description

fixes issue #552 - process description from comments Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - fix module tests Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - optionally read comments for output vars description Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - set default to true Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - run make docs Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - change option name Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - add option in doc generator; make docs Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - add config 'ReadComments' Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - Fix alphabetic order for 'ReadComments' setting Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - add read-comments in docs Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - add test for readcomments option Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com> - update 'read-comments' flag description Co-authored-by: Khosrow Moossavi <khos2ow@gmail.com> Signed-off-by: Poojitha Bikki <50849668+poojitha-bikki@users.noreply.github.com>
2026-03-27 04:48:33 +07:00 · 2021-09-17 20:13:04 -05:00
parent 5cd2b8f702
commit 045707beee
25 changed files with 129 additions and 39 deletions
--- a/README.md
+++ b/README.md
@@ -213,6 +213,7 @@ settings:
  html: true
  indent: 2
  lockfile: true
+  read-comments: true
  required: true
  sensitive: true
  type: true
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -81,6 +81,8 @@ func NewCommand() *cobra.Command {
 	cmd.PersistentFlags().BoolVar(&config.OutputValues.Enabled, "output-values", false, "inject output values into outputs (default false)")
 	cmd.PersistentFlags().StringVar(&config.OutputValues.From, "output-values-from", "", "inject output values from file into outputs (default \"\")")

+	cmd.PersistentFlags().BoolVar(&config.Settings.ReadComments, "read-comments", true, "use comments as description when description is empty")
+
 	// formatter subcommands
 	cmd.AddCommand(asciidoc.NewCommand(runtime, config))
 	cmd.AddCommand(json.NewCommand(runtime, config))
--- a/docs/reference/asciidoc-document.md
+++ b/docs/reference/asciidoc-document.md
@@ -40,6 +40,7 @@ terraform-docs asciidoc document [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --required                    show Required column or section (default true)
--- a/docs/reference/asciidoc-table.md
+++ b/docs/reference/asciidoc-table.md
@@ -40,6 +40,7 @@ terraform-docs asciidoc table [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --required                    show Required column or section (default true)
--- a/docs/reference/asciidoc.md
+++ b/docs/reference/asciidoc.md
@@ -43,6 +43,7 @@ terraform-docs asciidoc [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/json.md
+++ b/docs/reference/json.md
@@ -37,6 +37,7 @@ terraform-docs json [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/markdown-document.md
+++ b/docs/reference/markdown-document.md
@@ -42,6 +42,7 @@ terraform-docs markdown document [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --required                    show Required column or section (default true)
--- a/docs/reference/markdown-table.md
+++ b/docs/reference/markdown-table.md
@@ -42,6 +42,7 @@ terraform-docs markdown table [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --required                    show Required column or section (default true)
--- a/docs/reference/markdown.md
+++ b/docs/reference/markdown.md
@@ -45,6 +45,7 @@ terraform-docs markdown [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/pretty.md
+++ b/docs/reference/pretty.md
@@ -37,6 +37,7 @@ terraform-docs pretty [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/terraform-docs.md
+++ b/docs/reference/terraform-docs.md
@@ -31,6 +31,7 @@ terraform-docs [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/tfvars-hcl.md
+++ b/docs/reference/tfvars-hcl.md
@@ -37,6 +37,7 @@ terraform-docs tfvars hcl [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/tfvars-json.md
+++ b/docs/reference/tfvars-json.md
@@ -36,6 +36,7 @@ terraform-docs tfvars json [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/tfvars.md
+++ b/docs/reference/tfvars.md
@@ -32,6 +32,7 @@ Generate terraform.tfvars of inputs.
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/toml.md
+++ b/docs/reference/toml.md
@@ -36,6 +36,7 @@ terraform-docs toml [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/xml.md
+++ b/docs/reference/xml.md
@@ -36,6 +36,7 @@ terraform-docs xml [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/reference/yaml.md
+++ b/docs/reference/yaml.md
@@ -36,6 +36,7 @@ terraform-docs yaml [PATH] [flags]
      --output-template string      output template (default "<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->")
      --output-values               inject output values into outputs (default false)
      --output-values-from string   inject output values from file into outputs (default "")
+      --read-comments               use comments as description when description is empty (default true)
      --recursive                   update submodules recursively (default false)
      --recursive-path string       submodules path to recursively update (default "modules")
      --show strings                show section [all, data-sources, footer, header, inputs, modules, outputs, providers, requirements, resources]
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -107,6 +107,7 @@ settings:
  html: true
  indent: 2
  lockfile: true
+  read-comments: true
  required: true
  sensitive: true
  type: true
--- a/docs/user-guide/configuration/settings.md
+++ b/docs/user-guide/configuration/settings.md
@@ -27,6 +27,7 @@ settings:
  html: true
  indent: 2
  lockfile: true
+  read-comments: true
  required: true
  sensitive: true
  type: true
@@ -95,6 +96,13 @@ Indentation level of headings [available: 1, 2, 3, 4, 5].

 Read `.terraform.lock.hcl` to extract exact version of providers.

+### read-comments
+
+> since: `v0.16.0`\
+> scope: `global`
+
+Use comments from `tf` files for "Description" column (for inputs and outputs) when description is empty
+
 ### required

 > since: `v0.10.0`\
--- a/internal/cli/config.go
+++ b/internal/cli/config.go
@@ -40,15 +40,16 @@ var flagMappings = map[string]string{
 	"sort-by-required": "required",
 	"sort-by-type":     "type",

-	"anchor":      "settings.anchor",
-	"color":       "settings.color",
-	"default":     "settings.default",
-	"description": "settings.description",
-	"escape":      "settings.escape",
-	"indent":      "settings.indent",
-	"required":    "settings.required",
-	"sensitive":   "settings.sensitive",
-	"type":        "settings.type",
+	"anchor":        "settings.anchor",
+	"color":         "settings.color",
+	"default":       "settings.default",
+	"description":   "settings.description",
+	"escape":        "settings.escape",
+	"indent":        "settings.indent",
+	"read-comments": "settings.read-comments",
+	"required":      "settings.required",
+	"sensitive":     "settings.sensitive",
+	"type":          "settings.type",
 }

 // Config represents all the available config options that can be accessed and passed through CLI
@@ -376,34 +377,36 @@ func (s *sort) validate() error {
 }

 type settings struct {
-	Anchor      bool `mapstructure:"anchor"`
-	Color       bool `mapstructure:"color"`
-	Default     bool `mapstructure:"default"`
-	Description bool `mapstructure:"description"`
-	Escape      bool `mapstructure:"escape"`
-	HideEmpty   bool `mapstructure:"hide-empty"`
-	HTML        bool `mapstructure:"html"`
-	Indent      int  `mapstructure:"indent"`
-	LockFile    bool `mapstructure:"lockfile"`
-	Required    bool `mapstructure:"required"`
-	Sensitive   bool `mapstructure:"sensitive"`
-	Type        bool `mapstructure:"type"`
+	Anchor       bool `mapstructure:"anchor"`
+	Color        bool `mapstructure:"color"`
+	Default      bool `mapstructure:"default"`
+	Description  bool `mapstructure:"description"`
+	Escape       bool `mapstructure:"escape"`
+	HideEmpty    bool `mapstructure:"hide-empty"`
+	HTML         bool `mapstructure:"html"`
+	Indent       int  `mapstructure:"indent"`
+	LockFile     bool `mapstructure:"lockfile"`
+	ReadComments bool `mapstructure:"read-comments"`
+	Required     bool `mapstructure:"required"`
+	Sensitive    bool `mapstructure:"sensitive"`
+	Type         bool `mapstructure:"type"`
 }

 func defaultSettings() settings {
 	return settings{
-		Anchor:      true,
-		Color:       true,
-		Default:     true,
-		Description: false,
-		Escape:      true,
-		HideEmpty:   false,
-		HTML:        true,
-		Indent:      2,
-		LockFile:    true,
-		Required:    true,
-		Sensitive:   true,
-		Type:        true,
+		Anchor:       true,
+		Color:        true,
+		Default:      true,
+		Description:  false,
+		Escape:       true,
+		HideEmpty:    false,
+		HTML:         true,
+		Indent:       2,
+		LockFile:     true,
+		ReadComments: true,
+		Required:     true,
+		Sensitive:    true,
+		Type:         true,
 	}
 }

@@ -511,6 +514,9 @@ func (c *Config) extract() (*print.Settings, *terraform.Options) {
 	options.SortBy.Required = c.Sort.Enabled && c.Sort.By == sortRequired
 	options.SortBy.Type = c.Sort.Enabled && c.Sort.By == sortType

+	// read comments
+	options.ReadComments = c.Settings.ReadComments
+
 	// settings
 	settings.EscapeCharacters = c.Settings.Escape
 	settings.IndentLevel = c.Settings.Indent
--- a/internal/terraform/module.go
+++ b/internal/terraform/module.go
@@ -148,7 +148,7 @@ func loadModuleItems(tfmodule *tfconfig.Module, options *Options) (*Module, erro
 		return nil, err
 	}

-	inputs, required, optional := loadInputs(tfmodule)
+	inputs, required, optional := loadInputs(tfmodule, options)
 	modulecalls := loadModulecalls(tfmodule)
 	outputs, err := loadOutputs(tfmodule, options)
 	if err != nil {
@@ -265,7 +265,7 @@ func loadSection(options *Options, file string, section string) (string, error)
 	return strings.Join(sectionText, "\n"), nil
 }

-func loadInputs(tfmodule *tfconfig.Module) ([]*Input, []*Input, []*Input) {
+func loadInputs(tfmodule *tfconfig.Module, options *Options) ([]*Input, []*Input, []*Input) {
 	var inputs = make([]*Input, 0, len(tfmodule.Variables))
 	var required = make([]*Input, 0, len(tfmodule.Variables))
 	var optional = make([]*Input, 0, len(tfmodule.Variables))
@@ -273,7 +273,7 @@ func loadInputs(tfmodule *tfconfig.Module) ([]*Input, []*Input, []*Input) {
 	for _, input := range tfmodule.Variables {
 		// convert CRLF to LF early on (https://github.com/terraform-docs/terraform-docs/issues/305)
 		inputDescription := strings.ReplaceAll(input.Description, "\r\n", "\n")
-		if inputDescription == "" {
+		if inputDescription == "" && options.ReadComments {
 			inputDescription = loadComments(input.Pos.Filename, input.Pos.Line)
 		}

@@ -355,7 +355,7 @@ func loadOutputs(tfmodule *tfconfig.Module, options *Options) ([]*Output, error)
 	}
 	for _, o := range tfmodule.Outputs {
 		description := o.Description
-		if description == "" {
+		if description == "" && options.ReadComments {
 			description = loadComments(o.Pos.Filename, o.Pos.Line)
 		}
 		output := &Output{
--- a/internal/terraform/module_test.go
+++ b/internal/terraform/module_test.go
@@ -498,7 +498,8 @@ func TestLoadInputs(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			assert := assert.New(t)
 			module, _ := loadModule(filepath.Join("testdata", tt.path))
-			inputs, requireds, optionals := loadInputs(module)
+			options := NewOptions()
+			inputs, requireds, optionals := loadInputs(module, options)

 			assert.Equal(tt.expected.inputs, len(inputs))
 			assert.Equal(tt.expected.requireds, len(requireds))
@@ -556,7 +557,8 @@ func TestLoadInputsLineEnding(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			assert := assert.New(t)
 			module, _ := loadModule(filepath.Join("testdata", tt.path))
-			inputs, _, _ := loadInputs(module)
+			options := NewOptions()
+			inputs, _, _ := loadInputs(module, options)

 			assert.Equal(1, len(inputs))
 			assert.Equal(tt.expected, string(inputs[0].Description))
@@ -782,6 +784,49 @@ func TestLoadComments(t *testing.T) {
 	}
 }

+func TestReadComments(t *testing.T) {
+	tests := []struct {
+		name         string
+		path         string
+		fileName     string
+		readComments bool
+		expected     string
+	}{
+		{
+			name:         "Validate description when 'ReadComments' is false",
+			path:         "read-comments",
+			fileName:     "variables.tf",
+			readComments: false,
+			expected:     "",
+		},
+		{
+			name:         "Validate description when 'ReadComments' is true",
+			path:         "read-comments",
+			fileName:     "variables.tf",
+			readComments: true,
+			expected:     "B description",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert := assert.New(t)
+			options := NewOptions()
+			options.ReadComments = tt.readComments
+			module, err := loadModule(filepath.Join("testdata", tt.path))
+
+			assert.Nil(err)
+
+			inputs, _, _ := loadInputs(module, options)
+			assert.Equal(1, len(inputs))
+			assert.Equal(tt.expected, string(inputs[0].Description))
+
+			outputs, _ := loadOutputs(module, options)
+			assert.Equal(1, len(outputs))
+			assert.Equal(tt.expected, string(outputs[0].Description))
+		})
+	}
+}
+
 func TestSortItems(t *testing.T) {
 	type expected struct {
 		inputs    []string
--- a/internal/terraform/options.go
+++ b/internal/terraform/options.go
@@ -35,6 +35,7 @@ type Options struct {
 	SortBy           *SortBy
 	OutputValues     bool
 	OutputValuesPath string
+	ReadComments     bool
 }

 // NewOptions returns new instance of Options
@@ -49,6 +50,7 @@ func NewOptions() *Options {
 		SortBy:           &SortBy{Name: false, Required: false, Type: false},
 		OutputValues:     false,
 		OutputValuesPath: "",
+		ReadComments:     true,
 	}
 }

--- a/internal/terraform/testdata/read-comments/variables.tf
+++ b/internal/terraform/testdata/read-comments/variables.tf
@@ -0,0 +1,9 @@
+// B description
+variable "B" {
+  default = "b"
+}
+
+// B description
+output "B" {
+  value = "b"
+}
--- a/scripts/docs/generate.go
+++ b/scripts/docs/generate.go
@@ -183,6 +183,7 @@ func example(ref *reference) error {
 		SortBy: &terraform.SortBy{
 			Name: true,
 		},
+		ReadComments: true,
 	}

 	formatter, err := format.Factory(ref.Name, settings)