multiple documentation updates/fixes

docs/data-sources/waf_rules.md

@@ -121,6 +121,8 @@ resource "fastly_service_waf_configuration" "waf" {
 }
 ```
 
+
+
 ## Argument Reference
 
 ~> **Warning:** The data source's filters are applied using an **AND** boolean operator, so depending on the combination of filters, they may become mutually exclusive.

docs/resources/service_dictionary_items_v1.md

@@ -217,16 +217,6 @@ resource "fastly_service_dictionary_items_v1" "items" {
 }
 ```
 
-
-## Argument Reference
-
-The following arguments are supported:
-
-* `service_id` - (Required) The ID of the service that the dictionary belongs to
-* `dictionary_id` - (Required) The ID of the dictionary that the items belong to
-* `items` - (Optional) A map representing an entry in the dictionary, (key/value)
-
-
 ## Attributes Reference
 
 * [fastly-dictionary](https://developer.fastly.com/reference/api/dictionaries/dictionary/)
@@ -252,10 +242,10 @@ $ terraform state rm fastly_service_dictionary_items_v1.items
 
 ### Required
 
-- **dictionary_id** (String) The dictionary the items belong to
-- **service_id** (String) The service the dictionary belongs to
+- **dictionary_id** (String) The ID of the dictionary that the items belong to
+- **service_id** (String) The ID of the service that the dictionary belongs to
 
 ### Optional
 
 - **id** (String) The ID of this resource.
-- **items** (Map of String) Map of key/value pairs that make up an item in the dictionary
+- **items** (Map of String) A map representing an entry in the dictionary, (key/value)

docs/resources/service_dynamic_snippet_content_v1.md

@@ -173,15 +173,6 @@ resource "fastly_service_dynamic_snippet_content_v1" "my_dyn_content" {
 }
 ```
 
-
-## Argument Reference
-
-The following arguments are supported:
-
-* `service_id` - (Required) The ID of the service that the dynamic snippet belongs to
-* `snippet_id` - (Required) The ID of the dynamic snippet that the content belong to
-* `content` - (Required) The VCL code that specifies exactly what the snippet does.
-
 ## Attributes Reference
 
 * [fastly-vcl](https://developer.fastly.com/reference/api/vcl-services/vcl/)
@@ -207,9 +198,9 @@ $ terraform state rm fastly_service_dynamic_snippet_content_v1.content
 
 ### Required
 
-- **content** (String) The contents of the VCL dynamic snippet
-- **service_id** (String) Service Id
-- **snippet_id** (String) Snippet Id
+- **content** (String) The VCL code that specifies exactly what the snippet does
+- **service_id** (String) The ID of the service that the dynamic snippet belongs to
+- **snippet_id** (String) The ID of the dynamic snippet that the content belong to
 
 ### Optional
 

docs/resources/service_waf_configuration.md

@@ -628,68 +628,68 @@ $ terraform state rm fastly_service_waf_configuration.waf
 
 ### Required
 
-- **waf_id** (String) The service the WAF belongs to.
+- **waf_id** (String) The ID of the Web Application Firewall that the configuration belongs to
 
 ### Optional
 
-- **allowed_http_versions** (String) Allowed HTTP versions (default HTTP/1.0 HTTP/1.1 HTTP/2).
-- **allowed_methods** (String) A space-separated list of HTTP method names (default GET HEAD POST OPTIONS PUT PATCH DELETE).
-- **allowed_request_content_type** (String) Allowed request content types (default application/x-www-form-urlencoded|multipart/form-data|text/xml|application/xml|application/x-amf|application/json|text/plain).
-- **allowed_request_content_type_charset** (String) Allowed request content type charset (default utf-8|iso-8859-1|iso-8859-15|windows-1252).
-- **arg_length** (Number) The maximum number of arguments allowed (default 400).
-- **arg_name_length** (Number) The maximum allowed argument name length (default 100).
-- **combined_file_sizes** (Number) The maximum allowed size of all files (in bytes, default 10000000).
-- **critical_anomaly_score** (Number) Score value to add for critical anomalies (default 6).
-- **crs_validate_utf8_encoding** (Boolean) CRS validate UTF8 encoding.
-- **error_anomaly_score** (Number) Score value to add for error anomalies (default 5).
-- **high_risk_country_codes** (String) A space-separated list of country codes in ISO 3166-1 (two-letter) format.
-- **http_violation_score_threshold** (Number) HTTP violation threshold.
+- **allowed_http_versions** (String) Allowed HTTP versions
+- **allowed_methods** (String) A space-separated list of HTTP method names
+- **allowed_request_content_type** (String) Allowed request content types
+- **allowed_request_content_type_charset** (String) Allowed request content type charset
+- **arg_length** (Number) The maximum number of arguments allowed
+- **arg_name_length** (Number) The maximum allowed argument name length
+- **combined_file_sizes** (Number) The maximum allowed size of all files
+- **critical_anomaly_score** (Number) Score value to add for critical anomalies
+- **crs_validate_utf8_encoding** (Boolean) CRS validate UTF8 encoding
+- **error_anomaly_score** (Number) Score value to add for error anomalies
+- **high_risk_country_codes** (String) A space-separated list of country codes in ISO 3166-1 (two-letter) format
+- **http_violation_score_threshold** (Number) HTTP violation threshold
 - **id** (String) The ID of this resource.
-- **inbound_anomaly_score_threshold** (Number) Inbound anomaly threshold.
-- **lfi_score_threshold** (Number) Local file inclusion attack threshold.
-- **max_file_size** (Number) The maximum allowed file size, in bytes (default 10000000).
-- **max_num_args** (Number) The maximum number of arguments allowed (default 255).
-- **notice_anomaly_score** (Number) Score value to add for notice anomalies (default 4).
-- **paranoia_level** (Number) The configured paranoia level (default 1).
-- **php_injection_score_threshold** (Number) PHP injection threshold.
-- **rce_score_threshold** (Number) Remote code execution threshold.
-- **restricted_extensions** (String) A space-separated list of allowed file extensions (default .asa/ .asax/ .ascx/ .axd/ .backup/ .bak/ .bat/ .cdx/ .cer/ .cfg/ .cmd/ .com/ .config/ .conf/ .cs/ .csproj/ .csr/ .dat/ .db/ .dbf/ .dll/ .dos/ .htr/ .htw/ .ida/ .idc/ .idq/ .inc/ .ini/ .key/ .licx/ .lnk/ .log/ .mdb/ .old/ .pass/ .pdb/ .pol/ .printer/ .pwd/ .resources/ .resx/ .sql/ .sys/ .vb/ .vbs/ .vbproj/ .vsdisco/ .webinfo/ .xsd/ .xsx).
-- **restricted_headers** (String) A space-separated list of allowed header names (default /proxy/ /lock-token/ /content-range/ /translate/ /if/).
-- **rfi_score_threshold** (Number) Remote file inclusion attack threshold.
+- **inbound_anomaly_score_threshold** (Number) Inbound anomaly threshold
+- **lfi_score_threshold** (Number) Local file inclusion attack threshold
+- **max_file_size** (Number) The maximum allowed file size, in bytes
+- **max_num_args** (Number) The maximum number of arguments allowed
+- **notice_anomaly_score** (Number) Score value to add for notice anomalies
+- **paranoia_level** (Number) The configured paranoia level
+- **php_injection_score_threshold** (Number) PHP injection threshold
+- **rce_score_threshold** (Number) Remote code execution threshold
+- **restricted_extensions** (String) A space-separated list of allowed file extensions
+- **restricted_headers** (String) A space-separated list of allowed header names
+- **rfi_score_threshold** (Number) Remote file inclusion attack threshold
 - **rule** (Block Set) (see [below for nested schema](#nestedblock--rule))
 - **rule_exclusion** (Block Set) (see [below for nested schema](#nestedblock--rule_exclusion))
-- **session_fixation_score_threshold** (Number) Session fixation attack threshold.
-- **sql_injection_score_threshold** (Number) SQL injection attack threshold.
-- **total_arg_length** (Number) The maximum size of argument names and values (default 6400).
-- **warning_anomaly_score** (Number) Score value to add for warning anomalies.
-- **xss_score_threshold** (Number) XSS attack threshold.
+- **session_fixation_score_threshold** (Number) Session fixation attack threshold
+- **sql_injection_score_threshold** (Number) SQL injection attack threshold
+- **total_arg_length** (Number) The maximum size of argument names and values
+- **warning_anomaly_score** (Number) Score value to add for warning anomalies
+- **xss_score_threshold** (Number) XSS attack threshold
 
 <a id="nestedblock--rule"></a>
 ### Nested Schema for `rule`
 
 Required:
 
-- **modsec_rule_id** (Number) The Web Application Firewall rule's modsec ID.
-- **status** (String) The Web Application Firewall rule's status. Allowed values are (log, block and score).
+- **modsec_rule_id** (Number) The Web Application Firewall rule's modsecurity ID
+- **status** (String) The Web Application Firewall rule's status. Allowed values are (`log`, `block` and `score`)
 
 Optional:
 
-- **revision** (Number) The Web Application Firewall rule's revision.
+- **revision** (Number) The Web Application Firewall rule's revision. The latest revision will be used if this is not provided
 
 
 <a id="nestedblock--rule_exclusion"></a>
 ### Nested Schema for `rule_exclusion`
 
 Required:
 
-- **condition** (String) A conditional expression in VCL used to determine if the condition is met.
-- **exclusion_type** (String) The type of exclusion.
-- **name** (String) Name of the exclusion.
+- **condition** (String) A conditional expression in VCL used to determine if the condition is met
+- **exclusion_type** (String) The type of rule exclusion. Values are `rule` to exclude the specified rule(s), or `waf` to disable the Web Application Firewall
+- **name** (String) The name of rule exclusion
 
 Optional:
 
-- **modsec_rule_ids** (Set of Number) The modsec rule IDs to exclude.
+- **modsec_rule_ids** (Set of Number) Set of modsecurity IDs to be excluded. No rules should be provided when `exclusion_type` is `waf`. The rules need to be configured on the Web Application Firewall to be excluded
 
 Read-only:
 
-- **number** (Number) A sequential ID assigned to the exclusion.
+- **number** (Number) The numeric ID assigned to the WAF Rule Exclusion

fastly/base_fastly_service_v1.go

@@ -139,20 +139,20 @@ func resourceService(serviceDef ServiceDefinition) *schema.Resource {
 			"name": {
 				Type:        schema.TypeString,
 				Required:    true,
-				Description: "Unique name for this Service",
+				Description: "The unique name for the Service to create",
 			},
 
 			"comment": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				Default:     "Managed by Terraform",
-				Description: "A personal freeform descriptive note",
+				Description: "Description field for the service. Default `Managed by Terraform`",
 			},
 
 			"version_comment": {
 				Type:        schema.TypeString,
 				Optional:    true,
-				Description: "A personal freeform descriptive note",
+				Description: "Description field for the version",
 			},
 
 			// Active Version represents the currently activated version in Fastly. In
@@ -162,7 +162,7 @@ func resourceService(serviceDef ServiceDefinition) *schema.Resource {
 			"active_version": {
 				Type:        schema.TypeInt,
 				Computed:    true,
-				Description: "The currently active version of your Fastly Service.",
+				Description: "The currently active version of your Fastly Service",
 			},
 
 			// Cloned Version represents the latest cloned version by the provider. It
@@ -174,12 +174,12 @@ func resourceService(serviceDef ServiceDefinition) *schema.Resource {
 			"cloned_version": {
 				Type:        schema.TypeInt,
 				Computed:    true,
-				Description: "The latest cloned version by the provider. The value gets only set after running `terraform apply`.",
+				Description: "The latest cloned version by the provider. The value gets only set after running `terraform apply`",
 			},
 
 			"activate": {
 				Type:        schema.TypeBool,
-				Description: "Conditionally prevents the Service from being activated",
+				Description: "Conditionally prevents the Service from being activated. The apply step will continue to create a new draft version but will not activate it if this is set to `false`. Default `true`",
 				Default:     true,
 				Optional:    true,
 			},

fastly/block_fastly_service_v1_acl.go

@@ -105,13 +105,13 @@ func (h *ACLServiceAttributeHandler) Register(s *schema.Resource) error {
 				"name": {
 					Type:        schema.TypeString,
 					Required:    true,
-					Description: "Unique name to refer to this ACL",
+					Description: "A unique name to identify this ACL",
 				},
 				// Optional fields
 				"acl_id": {
 					Type:        schema.TypeString,
 					Computed:    true,
-					Description: "Generated acl id",
+					Description: "The ID of the ACL",
 				},
 			},
 		},

fastly/block_fastly_service_v1_backend.go

@@ -245,7 +245,7 @@ func (h *BackendServiceAttributeHandler) Register(s *schema.Resource) error {
 		"name": {
 			Type:        schema.TypeString,
 			Required:    true,
-			Description: "A name for this Backend",
+			Description: "Name for this Backend. Must be unique to this Service",
 		},
 		"address": {
 			Type:        schema.TypeString,
@@ -257,49 +257,49 @@ func (h *BackendServiceAttributeHandler) Register(s *schema.Resource) error {
 			Type:        schema.TypeBool,
 			Optional:    true,
 			Default:     true,
-			Description: "Should this Backend be load balanced",
+			Description: "Denotes if this Backend should be included in the pool of backends that requests are load balanced against. Default `true`",
 		},
 		"between_bytes_timeout": {
 			Type:        schema.TypeInt,
 			Optional:    true,
 			Default:     10000,
-			Description: "How long to wait between bytes in milliseconds",
+			Description: "How long to wait between bytes in milliseconds. Default `10000`",
 		},
 		"connect_timeout": {
 			Type:        schema.TypeInt,
 			Optional:    true,
 			Default:     1000,
-			Description: "How long to wait for a timeout in milliseconds",
+			Description: "How long to wait for a timeout in milliseconds. Default `1000`",
 		},
 		"error_threshold": {
 			Type:        schema.TypeInt,
 			Optional:    true,
 			Default:     0,
-			Description: "Number of errors to allow before the Backend is marked as down",
+			Description: "Number of errors to allow before the Backend is marked as down. Default `0`",
 		},
 		"first_byte_timeout": {
 			Type:        schema.TypeInt,
 			Optional:    true,
 			Default:     15000,
-			Description: "How long to wait for the first bytes in milliseconds",
+			Description: "How long to wait for the first bytes in milliseconds. Default `15000`",
 		},
 		"healthcheck": {
 			Type:        schema.TypeString,
 			Optional:    true,
 			Default:     "",
-			Description: "The healthcheck name that should be used for this Backend",
+			Description: "Name of a defined `healthcheck` to assign to this backend",
 		},
 		"max_conn": {
 			Type:        schema.TypeInt,
 			Optional:    true,
 			Default:     200,
-			Description: "Maximum number of connections for this Backend",
+			Description: "Maximum number of connections for this Backend. Default `200`",
 		},
 		"port": {
 			Type:        schema.TypeInt,
 			Optional:    true,
 			Default:     80,
-			Description: "The port number Backend responds on. Default 80",
+			Description: "The port number on which the Backend responds. Default `80`",
 		},
 		"override_host": {
 			Type:        schema.TypeString,
@@ -310,13 +310,13 @@ func (h *BackendServiceAttributeHandler) Register(s *schema.Resource) error {
 			Type:        schema.TypeString,
 			Optional:    true,
 			Default:     "",
-			Description: "The POP of the shield designated to reduce inbound load.",
+			Description: "The POP of the shield designated to reduce inbound load. Valid values for `shield` are included in the `GET /datacenters` API response",
 		},
 		"use_ssl": {
 			Type:        schema.TypeBool,
 			Optional:    true,
 			Default:     false,
-			Description: "Whether or not to use SSL to reach the Backend",
+			Description: "Whether or not to use SSL to reach the Backend. Default `false`",
 		},
 		"max_tls_version": {
 			Type:        schema.TypeString,
@@ -334,19 +334,19 @@ func (h *BackendServiceAttributeHandler) Register(s *schema.Resource) error {
 			Type:        schema.TypeString,
 			Optional:    true,
 			Default:     "",
-			Description: "Comma sepparated list of ciphers",
+			Description: "Comma separated list of OpenSSL Ciphers to try when negotiating to the backend",
 		},
 		"ssl_check_cert": {
 			Type:        schema.TypeBool,
 			Optional:    true,
 			Default:     true,
-			Description: "Be strict on checking SSL certs",
+			Description: "Be strict about checking SSL certs. Default `true`",
 		},
 		"ssl_hostname": {
 			Type:        schema.TypeString,
 			Optional:    true,
 			Default:     "",
-			Description: "SSL certificate hostname",
+			Description: "Used for both SNI during the TLS handshake and to validate the cert",
 			Deprecated:  "Use ssl_cert_hostname and ssl_sni_hostname instead.",
 		},
 		"ssl_ca_cert": {
@@ -359,34 +359,33 @@ func (h *BackendServiceAttributeHandler) Register(s *schema.Resource) error {
 			Type:        schema.TypeString,
 			Optional:    true,
 			Default:     "",
-			Description: "SSL certificate hostname for cert verification",
+			Description: "Overrides ssl_hostname, but only for cert verification. Does not affect SNI at all",
 		},
 		"ssl_sni_hostname": {
 			Type:        schema.TypeString,
 			Optional:    true,
 			Default:     "",
-			Description: "SSL certificate hostname for SNI verification",
+			Description: "Overrides ssl_hostname, but only for SNI in the handshake. Does not affect cert validation at all",
 		},
 		"ssl_client_cert": {
 			Type:        schema.TypeString,
 			Optional:    true,
 			Default:     "",
-			Description: "SSL certificate file for client connections to the backend.",
+			Description: "Client certificate attached to origin. Used when connecting to the backend",
 			Sensitive:   true,
 		},
 		"ssl_client_key": {
 			Type:        schema.TypeString,
 			Optional:    true,
 			Default:     "",
-			Description: "SSL key file for client connections to backend.",
+			Description: "Client key attached to origin. Used when connecting to the backend",
 			Sensitive:   true,
 		},
-
 		"weight": {
 			Type:        schema.TypeInt,
 			Optional:    true,
 			Default:     100,
-			Description: "The portion of traffic to send to a specific origins. Each origin receives weight/total of the traffic.",
+			Description: "The [portion of traffic](https://docs.fastly.com/en/guides/load-balancing-configuration#how-weight-affects-load-balancing) to send to this Backend. Each Backend receives weight / total of the traffic. Default `100`",
 		},
 	}