Extract leading comments for resources and modules

Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
terraform-docs · Sep 29, 2021 · f3c9238 · f3c9238
1 parent 5f00545
commit f3c9238
Show file tree

Hide file tree

Showing 26 changed files with 196 additions and 55 deletions.
diff --git a/docs/reference/json.md b/docs/reference/json.md
@@ -306,22 +306,26 @@ generates the following output:
         {
           "name": "bar",
           "source": "baz",
-          "version": "4.5.6"
+          "version": "4.5.6",
+          "description": null
         },
         {
           "name": "baz",
           "source": "baz",
-          "version": "4.5.6"
+          "version": "4.5.6",
+          "description": null
         },
         {
           "name": "foo",
           "source": "bar",
-          "version": "1.2.3"
+          "version": "1.2.3",
+          "description": "another type of description for module foo"
         },
         {
           "name": "foobar",
           "source": "git@github.com:module/path",
-          "version": "v7.8.9"
+          "version": "v7.8.9",
+          "description": null
         }
       ],
       "outputs": [
@@ -394,39 +398,44 @@ generates the following output:
           "provider": "foo",
           "source": "https://registry.acme.com/foo",
           "mode": "managed",
-          "version": "latest"
+          "version": "latest",
+          "description": null
         },
         {
           "type": "resource",
           "name": "foo",
           "provider": "null",
           "source": "hashicorp/null",
           "mode": "managed",
-          "version": "latest"
+          "version": "latest",
+          "description": null
         },
         {
           "type": "private_key",
           "name": "baz",
           "provider": "tls",
           "source": "hashicorp/tls",
           "mode": "managed",
-          "version": "latest"
+          "version": "latest",
+          "description": "this description for tls_private_key.baz which can be multiline."
         },
         {
           "type": "caller_identity",
           "name": "current",
           "provider": "aws",
           "source": "hashicorp/aws",
           "mode": "data",
-          "version": "latest"
+          "version": "latest",
+          "description": null
         },
         {
           "type": "caller_identity",
           "name": "ident",
           "provider": "aws",
           "source": "hashicorp/aws",
           "mode": "data",
-          "version": "latest"
+          "version": "latest",
+          "description": null
         }
       ]
     }

diff --git a/docs/reference/toml.md b/docs/reference/toml.md
@@ -290,21 +290,25 @@ generates the following output:
       name = "bar"
       source = "baz"
       version = "4.5.6"
+      description = ""
 
     [[modules]]
       name = "baz"
       source = "baz"
       version = "4.5.6"
+      description = ""
 
     [[modules]]
       name = "foo"
       source = "bar"
       version = "1.2.3"
+      description = "another type of description for module foo"
 
     [[modules]]
       name = "foobar"
       source = "git@github.com:module/path"
       version = "v7.8.9"
+      description = ""
 
     [[outputs]]
       name = "output-0.12"
@@ -370,6 +374,7 @@ generates the following output:
       source = "https://registry.acme.com/foo"
       mode = "managed"
       version = "latest"
+      description = ""
 
     [[resources]]
       type = "resource"
@@ -378,6 +383,7 @@ generates the following output:
       source = "hashicorp/null"
       mode = "managed"
       version = "latest"
+      description = ""
 
     [[resources]]
       type = "private_key"
@@ -386,6 +392,7 @@ generates the following output:
       source = "hashicorp/tls"
       mode = "managed"
       version = "latest"
+      description = "this description for tls_private_key.baz which can be multiline."
 
     [[resources]]
       type = "caller_identity"
@@ -394,6 +401,7 @@ generates the following output:
       source = "hashicorp/aws"
       mode = "data"
       version = "latest"
+      description = ""
 
     [[resources]]
       type = "caller_identity"
@@ -402,5 +410,6 @@ generates the following output:
       source = "hashicorp/aws"
       mode = "data"
       version = "latest"
+      description = ""
 
 [examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples
diff --git a/docs/reference/xml.md b/docs/reference/xml.md
@@ -306,21 +306,25 @@ generates the following output:
           <name>bar</name>
           <source>baz</source>
           <version>4.5.6</version>
+          <description xsi:nil="true"></description>
         </module>
         <module>
           <name>baz</name>
           <source>baz</source>
           <version>4.5.6</version>
+          <description xsi:nil="true"></description>
         </module>
         <module>
           <name>foo</name>
           <source>bar</source>
           <version>1.2.3</version>
+          <description>another type of description for module foo</description>
         </module>
         <module>
           <name>foobar</name>
           <source>git@github.com:module/path</source>
           <version>v7.8.9</version>
+          <description xsi:nil="true"></description>
         </module>
       </modules>
       <outputs>
@@ -394,6 +398,7 @@ generates the following output:
           <source>https://registry.acme.com/foo</source>
           <mode>managed</mode>
           <version>latest</version>
+          <description xsi:nil="true"></description>
         </resource>
         <resource>
           <type>resource</type>
@@ -402,6 +407,7 @@ generates the following output:
           <source>hashicorp/null</source>
           <mode>managed</mode>
           <version>latest</version>
+          <description xsi:nil="true"></description>
         </resource>
         <resource>
           <type>private_key</type>
@@ -410,6 +416,7 @@ generates the following output:
           <source>hashicorp/tls</source>
           <mode>managed</mode>
           <version>latest</version>
+          <description>this description for tls_private_key.baz which can be multiline.</description>
         </resource>
         <resource>
           <type>caller_identity</type>
@@ -418,6 +425,7 @@ generates the following output:
           <source>hashicorp/aws</source>
           <mode>data</mode>
           <version>latest</version>
+          <description xsi:nil="true"></description>
         </resource>
         <resource>
           <type>caller_identity</type>
@@ -426,6 +434,7 @@ generates the following output:
           <source>hashicorp/aws</source>
           <mode>data</mode>
           <version>latest</version>
+          <description xsi:nil="true"></description>
         </resource>
       </resources>
     </module>

diff --git a/docs/reference/yaml.md b/docs/reference/yaml.md
@@ -284,15 +284,19 @@ generates the following output:
       - name: bar
         source: baz
         version: 4.5.6
+        description: null
       - name: baz
         source: baz
         version: 4.5.6
+        description: null
       - name: foo
         source: bar
         version: 1.2.3
+        description: another type of description for module foo
       - name: foobar
         source: git@github.com:module/path
         version: v7.8.9
+        description: null
     outputs:
       - name: output-0.12
         description: terraform 0.12 only
@@ -334,29 +338,34 @@ generates the following output:
         source: https://registry.acme.com/foo
         mode: managed
         version: latest
+        description: null
       - type: resource
         name: foo
         provider: "null"
         source: hashicorp/null
         mode: managed
         version: latest
+        description: null
       - type: private_key
         name: baz
         provider: tls
         source: hashicorp/tls
         mode: managed
         version: latest
+        description: this description for tls_private_key.baz which can be multiline.
       - type: caller_identity
         name: current
         provider: aws
         source: hashicorp/aws
         mode: data
         version: latest
+        description: null
       - type: caller_identity
         name: ident
         provider: aws
         source: hashicorp/aws
         mode: data
         version: latest
+        description: null
 
 [examples]: https://github.com/terraform-docs/terraform-docs/tree/master/examples
diff --git a/examples/main.tf b/examples/main.tf
@@ -50,6 +50,8 @@ terraform {
   }
 }
 
+// this description for tls_private_key.baz
+// which can be multiline.
 resource "tls_private_key" "baz" {}
 resource "foo_resource" "baz" {}
 
@@ -68,6 +70,7 @@ module "bar" {
   version = "4.5.6"
 }
 
+# another type of description for module foo
 module "foo" {
   source  = "bar"
   version = "1.2.3"

diff --git a/format/testdata/json/json-Base.golden b/format/testdata/json/json-Base.golden
@@ -249,22 +249,26 @@
     {
       "name": "bar",
       "source": "baz",
-      "version": "4.5.6"
+      "version": "4.5.6",
+      "description": null
     },
     {
       "name": "foo",
       "source": "bar",
-      "version": "1.2.3"
+      "version": "1.2.3",
+      "description": "another type of description for module foo"
     },
     {
       "name": "baz",
       "source": "baz",
-      "version": "4.5.6"
+      "version": "4.5.6",
+      "description": null
     },
     {
       "name": "foobar",
       "source": "git@github.com:module/path",
-      "version": "v7.8.9"
+      "version": "v7.8.9",
+      "description": null
     }
   ],
   "outputs": [
@@ -337,39 +341,44 @@
       "provider": "foo",
       "source": "https://registry.acme.com/foo",
       "mode": "managed",
-      "version": "latest"
+      "version": "latest",
+      "description": null
     },
     {
       "type": "resource",
       "name": "foo",
       "provider": "null",
       "source": "hashicorp/null",
       "mode": "managed",
-      "version": "latest"
+      "version": "latest",
+      "description": null
     },
     {
       "type": "private_key",
       "name": "baz",
       "provider": "tls",
       "source": "hashicorp/tls",
       "mode": "managed",
-      "version": "latest"
+      "version": "latest",
+      "description": "this description for tls_private_key.baz which can be multiline."
     },
     {
       "type": "caller_identity",
       "name": "current",
       "provider": "aws",
       "source": "hashicorp/aws",
       "mode": "data",
-      "version": "latest"
+      "version": "latest",
+      "description": null
     },
     {
       "type": "caller_identity",
       "name": "ident",
       "provider": "aws",
       "source": "hashicorp/aws",
       "mode": "data",
-      "version": "latest"
+      "version": "latest",
+      "description": null
     }
   ]
 }