diff --git a/README.md b/README.md index 9140dc7..8470b6a 100644 --- 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 diff --git a/cmd/root.go b/cmd/root.go index 0897930..ec771fc 100644 --- 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)) diff --git a/docs/reference/asciidoc-document.md b/docs/reference/asciidoc-document.md index 4a64885..0d26d6d 100644 --- 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 "\n{{ .Content }}\n") --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) diff --git a/docs/reference/asciidoc-table.md b/docs/reference/asciidoc-table.md index 7737ff7..b343f96 100644 --- 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 "\n{{ .Content }}\n") --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) diff --git a/docs/reference/asciidoc.md b/docs/reference/asciidoc.md index f82ef3e..783a327 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/json.md b/docs/reference/json.md index 8cf020a..6659c84 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/markdown-document.md b/docs/reference/markdown-document.md index 3859beb..b614611 100644 --- 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 "\n{{ .Content }}\n") --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) diff --git a/docs/reference/markdown-table.md b/docs/reference/markdown-table.md index 2167b25..f3775a8 100644 --- 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 "\n{{ .Content }}\n") --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) diff --git a/docs/reference/markdown.md b/docs/reference/markdown.md index bd2d944..ab947d2 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/pretty.md b/docs/reference/pretty.md index dc4fef7..d3e798d 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/terraform-docs.md b/docs/reference/terraform-docs.md index 97e8de3..ccc71e5 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/tfvars-hcl.md b/docs/reference/tfvars-hcl.md index e7b2354..7abc874 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/tfvars-json.md b/docs/reference/tfvars-json.md index e0e4184..0354b35 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/tfvars.md b/docs/reference/tfvars.md index 4721b00..38834dc 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/toml.md b/docs/reference/toml.md index b321db8..75c3eb6 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/xml.md b/docs/reference/xml.md index df98dc4..9788b53 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/reference/yaml.md b/docs/reference/yaml.md index 11f9c1a..79a1667 100644 --- 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 "\n{{ .Content }}\n") --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] diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 03086e5..31d6147 100644 --- 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 diff --git a/docs/user-guide/configuration/settings.md b/docs/user-guide/configuration/settings.md index addd64a..7eb4bcb 100644 --- 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`\ diff --git a/internal/cli/config.go b/internal/cli/config.go index 5c53171..c4666dd 100644 --- 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 diff --git a/internal/terraform/module.go b/internal/terraform/module.go index f46fb18..c651149 100644 --- 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{ diff --git a/internal/terraform/module_test.go b/internal/terraform/module_test.go index 7b8589b..785a92e 100644 --- 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 diff --git a/internal/terraform/options.go b/internal/terraform/options.go index 8126b3d..542b594 100644 --- 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, } } diff --git a/internal/terraform/testdata/read-comments/variables.tf b/internal/terraform/testdata/read-comments/variables.tf new file mode 100644 index 0000000..be42f66 --- /dev/null +++ b/internal/terraform/testdata/read-comments/variables.tf @@ -0,0 +1,9 @@ +// B description +variable "B" { + default = "b" +} + +// B description +output "B" { + value = "b" +} diff --git a/scripts/docs/generate.go b/scripts/docs/generate.go index bbf4058..03a6459 100644 --- 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)