[Feature]: automatic generation of variable description

[matt-FFFFFF]

Module Name

pre-commit

Description

Using terraform-docs, it is sometimes useful to use the HEREDOC format to provide the variable description.

e.g. generate a markdown document to place in the variable description in HEREDOC format based on this:

variable "complex" {
  type = map(object({
    name                = string # the name of the resource
    address_space       = list(string) # these comments are used by the description generator to include the markdown
    location            = string
    resource_group_name = string

    bgp_community                   = optional(string)
    ddos_protection_plan_id         = optional(string)
    dns_servers                     = optional(list(string))
    flow_timeout_in_minutes         = optional(number, 4)
    mesh_peering_enabled            = optional(bool, true)
    resource_group_creation_enabled = optional(bool, true)
    resource_group_lock_enabled     = optional(bool, true)
    resource_group_lock_name        = optional(string)
    resource_group_tags             = optional(map(string))
    routing_address_space           = optional(list(string), [])
    hub_router_ip_address           = optional(string)
    tags                            = optional(map(string), {})

    route_table_entries = optional(map(object({
      name           = string
      address_prefix = string
      next_hop_type  = string

      has_bgp_override    = optional(bool, false)
      next_hop_ip_address = optional(string)
    })), {})

    subnets = optional(map(object(
      {
        address_prefixes = list(string)
        nat_gateway = optional(object({
          id = string
        }))
        network_security_group = optional(object({
          id = string
        }))
        private_endpoint_network_policies_enabled     = optional(bool, true)
        private_link_service_network_policies_enabled = optional(bool, true)
        assign_generated_route_table                  = optional(bool, true)
        external_route_table_id                       = optional(string)
        service_endpoints                             = optional(set(string))
        service_endpoint_policy_ids                   = optional(set(string))
        delegations = optional(list(
          object(
            {
              name = string
              service_delegation = object({
                name    = string
                actions = optional(list(string))
              })
            }
          )
        ))
      }
    )), {})

    firewall = optional(object({
      sku_name              = string
      sku_tier              = string
      subnet_address_prefix = string
      subnet_route_table_id = optional(string)
      name                  = optional(string)
      dns_servers           = optional(list(string))
      firewall_policy_id    = optional(string)
      private_ip_ranges     = optional(list(string))
      threat_intel_mode     = optional(string, "Alert")
      zones                 = optional(list(string))
      tags                  = optional(map(string))
      default_ip_configuration = optional(object({
        name = optional(string)
        public_ip_config = optional(object({
          name       = optional(set(string))
          zones      = optional(set(string))
          ip_version = optional(string)
          sku_tier   = optional(string, "Regional")
        }))
      }))
    }))
  }))
  default     = true
  description = <<DESCRIPTION
A map of objects with the following attributes:

- name - (string) the name of the resource
- address_space - list(string) these comments are used by the description generator to include the markdown
...
- route table_entries - (optional) (map(object))) with the following attributes
  - attrib - (string) you get it
DESCRIPTION
}

Example usage

No response

Other information

No response