docs

Author: AleksaC

README.md

@@ -1,6 +1,6 @@
 # TFLint Misc Ruleset
 
-Tflint ruleset containing miscellaneous rules that don't fit into other rulesets.
+TFLint ruleset containing miscellaneous rules that don't fit into other rulesets.
 
 ## Installation
 
@@ -18,7 +18,7 @@ plugin "misc" {
 
 |Name|Description|Severity|Enabled|Link|
 | --- | --- | --- | --- | --- |
-|no_multiline_comments|Disallows usage of multiline comments|WARNING|✔|https://github.com/AleksaC/tflint-ruleset-misc/tree/main/docs/rules/no_multiline_comments.md|
+|no_multiline_comments|Disallows usage of multiline comments|WARNING|✔|[🔗](https://github.com/AleksaC/tflint-ruleset-misc/tree/main/docs/rules/no_multiline_comments.md)|
 
 ## Building the plugin
 

docs/rules/no_multiline_comments.md

@@ -1 +1,82 @@
 # No Multiline Comments
+
+Disallows usage of multiline comments
+
+## Configuration
+
+Name | Default | Value
+--- | --- | ---
+enabled | true | Boolean
+single_line_only | false | Boolean
+
+```hcl
+rule "no_multiline_comments" {
+  enabled = true
+
+  single_line_only = false
+}
+```
+
+## Example
+
+Disallows usage of multi-line comments.
+
+```hcl
+# Good
+/*
+Bad
+*/
+```
+
+```
+Warning: Multiline comments are not allowed. Replace the comment with single-line comment(s) (no_multiline_comments)
+
+  on t.tf line 2:
+   2: /*
+   3: Bad
+   4: */
+
+Reference: https://github.com/AleksaC/tflint-ruleset-misc
+```
+
+### single_line_only = false
+
+Disallows usage of multi-line comments for single-line comments only.
+
+```hcl
+/*
+Good
+*/
+/* Bad */
+```
+
+```
+Warning: Using multiline comment syntax for single-line comments is not allowed. Use `#` instead. (no_multiline_comments)
+
+  on t.tf line 4:
+   4: /* Bad */
+
+Reference: https://github.com/AleksaC/tflint-ruleset-misc
+```
+
+## Why
+
+Terraform supports multiline comments using `/*` and `*/` as delimiters. In practice
+multiline comments are rarely needed and can be replaced by multiple single-line ones.
+Unline single-line comments, multiline comments can be placed in the middle of
+expressions. However, I have yet to see a case where putting a comment inside the
+expression has any benefit over putting it on the line above or at the end of the line,
+but I can easily think of cases where that would hurt readability as well as make
+it harder to build tools that parse expressions as they need to be aware that a multiline
+comment can pop up pretty much everywhere.
+
+So banning multiline comments prevents putting them in weird places, makes the code
+more consistent and subjectively more aesthetically pleasing.
+
+If you still want to use multiline comments, this rule provides an option to ban them
+for comments that don't span multiple lines, allowing their usage only for actual
+multiline comments.
+
+## How To Fix
+
+Replace multi-line comment with single-line comment(s).