Place id attribute in documentation "Read-Only" group by default

This still allows arbitrary definition of `id` where a tailor-made `.Description` can be provided: it's just the default that is changing to something more sensible.

Also, updated README to guide developers.

Co-authored-by: Nicholas Muesch <nicholas.muesch@datadoghq.com>
Co-authored-by: Oliver Ford <dev.github@ojford.com>

.go-version

@@ -1 +1 @@
-1.17.8
+1.17.9

CHANGELOG.md

@@ -6,22 +6,23 @@ ENHANCEMENTS:
 
 BUG FIXES:
 
-* cmd/tflugindocs: Allow documentation generation for schemas containing empty nested attributes or empty nested blocks ([#99](https://github.com/hashicorp/terraform-plugin-docs/pull/99), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)) 
+* cmd/tflugindocs: Support for schemas containing empty nested attributes or empty nested blocks ([#99](https://github.com/hashicorp/terraform-plugin-docs/pull/99), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)).
+* schemamd: Attribute `ID` is considered "Read Only", unless there's a description defined, in which case it's handled like any other attribute in the schema ([#46](https://github.com/hashicorp/terraform-plugin-docs/pull/46), [#XX](https://github.com/hashicorp/terraform-plugin-docs/pull/XX)).
 
 # 0.7.0 (March 15, 2022)
 
 ENHANCEMENTS:
 
-* cmd/tfplugindocs: Use existing Terraform CLI binary if available on PATH, otherwise download latest Terraform CLI binary (https://github.com/hashicorp/terraform-plugin-docs/pull/124)
-* cmd/tfplugindocs: Added `tf-version` flag for specifying Terraform CLI binary version to download, superseding the PATH lookup (https://github.com/hashicorp/terraform-plugin-docs/pull/124)
+* cmd/tfplugindocs: Use existing Terraform CLI binary if available on PATH, otherwise download latest Terraform CLI binary (https://github.com/hashicorp/terraform-plugin-docs/pull/124).
+* cmd/tfplugindocs: Added `tf-version` flag for specifying Terraform CLI binary version to download, superseding the PATH lookup (https://github.com/hashicorp/terraform-plugin-docs/pull/124).
 
 BUG FIXES:
 
-* cmd/tfplugindocs: Swapped `.Type` and `.Name` resource and data source template fields so they correctly align (https://github.com/hashicorp/terraform-plugin-docs/pull/44)
-* schemamd: Switched attribute name rendering from bold text to code blocks so the Terraform Registry treats them as anchor links (https://github.com/hashicorp/terraform-plugin-docs/pull/59)
+* cmd/tfplugindocs: Swapped `.Type` and `.Name` resource and data source template fields so they correctly align (https://github.com/hashicorp/terraform-plugin-docs/pull/44).
+* schemamd: Switched attribute name rendering from bold text to code blocks so the Terraform Registry treats them as anchor links (https://github.com/hashicorp/terraform-plugin-docs/pull/59).
 
 # 0.6.0 (March 14, 2022)
 
 NOTES:
 
-* The `github.com/hashicorp/terraform-exec` dependency has been updated to match `terraform-plugin-sdk`, which replaced the removed `tfinstall` package with `github.com/hashicorp/hc-install`. This will resolve Go build errors for projects that import both `terraform-plugin-docs` and `terraform-plugin-sdk`.
+* dependencies: `github.com/hashicorp/terraform-exec` dependency has been updated to match `terraform-plugin-sdk`, which replaced the removed `tfinstall` package with `github.com/hashicorp/hc-install`. This will resolve Go build errors for projects that import both `terraform-plugin-docs` and `terraform-plugin-sdk`.

README.md

@@ -21,6 +21,27 @@ When you run `tfplugindocs` from root directory of the provider the tool takes t
 
 You can see an example of the templates and output in [paultyng/terraform-provider-unifi](https://github.com/paultyng/terraform-provider-unifi) and browse the generated docs in the [Terraform Registry](https://registry.terraform.io/providers/paultyng/unifi/latest/docs).
 
+#### About the `id` attribute
+
+If the provider schema didn't set `id` for the given resource/data-source, the documentation generated
+will place it under the "Read Only" section and provide a simple description.
+
+Otherwise, the provider developer can set an arbitrary description like this:
+
+```golang
+    // ...
+    Schema: map[string]*schema.Schema{
+        // ...
+        "id": {
+            Type:     schema.TypeString,
+            Computed: true,
+            Description: "Unique identifier for this resource",
+		},
+        // ...
+    }
+    // ...
+```
+
 ### Conventional Paths
 
 The generation of missing documentation is based on a number of assumptions / conventional paths:

schemamd/render.go

@@ -70,10 +70,6 @@ func writeAttribute(w io.Writer, path []string, att *tfjson.SchemaAttribute, gro
 		return nil, err
 	}
 
-	if name == "id" && att.Description == "" {
-		att.Description = "The ID of this resource."
-	}
-
 	if att.AttributeNestedType == nil {
 		err = WriteAttributeDescription(w, att, false)
 	} else {
@@ -225,7 +221,18 @@ nameLoop:
 			}
 		} else if childAtt, ok := block.Attributes[n]; ok {
 			for i, gf := range groupFilters {
-				if gf.filterAttribute(childAtt) {
+				// By default, the attribute `id` is place in the "Read-Only" group
+				// if the provider schema contained no `.Description` for it.
+				//
+				// If a `.Description` is provided instead, the behaviour will be the
+				// same as for every other attribute.
+				if strings.ToLower(n) == "id" && childAtt.Description == "" {
+					if strings.Contains(gf.topLevelTitle, "Read-Only") {
+						childAtt.Description = "The ID of this resource."
+						groups[i] = append(groups[i], n)
+						continue nameLoop
+					}
+				} else if gf.filterAttribute(childAtt) {
 					groups[i] = append(groups[i], n)
 					continue nameLoop
 				}