docs: add descriptions and improve overall function documentation

.changes/unreleased/v0.14.0.md → .changes/v0.14.0.md

@@ -3,6 +3,8 @@
 ENHANCEMENTS:
 
 * Upgrade to Go 1.23.0 ([#66](https://github.com/hashicorp/terraform-provider-assert/issues/66))
+* Added descriptions to each function in the documentation ([#69](https://github.com/hashicorp/terraform-provider-assert/issues/69))
+* Consolidated the IP Address and CIDR Function sections into a single Network Functions category in the registry. ([#69](https://github.com/hashicorp/terraform-provider-assert/issues/69))
 
 BUG FIXES:
 

CHANGELOG.md

@@ -0,0 +1,18 @@
+## v0.15.0 (September 25, 2024)
+
+## v0.14.0 (September 25, 2024)
+
+ENHANCEMENTS:
+
+* Upgrade to Go 1.23.0 ([#66](https://github.com/hashicorp/terraform-provider-assert/issues/66))
+* Added descriptions to each function in the documentation ([#69](https://github.com/hashicorp/terraform-provider-assert/issues/69))
+* Consolidated the IP Address and CIDR Function sections into a single Network Functions category in the registry. ([#69](https://github.com/hashicorp/terraform-provider-assert/issues/69))
+
+BUG FIXES:
+
+* Correct test regex pattern ([#66](https://github.com/hashicorp/terraform-provider-assert/issues/66))
+
+FEATURES:
+
+* Added changie for changelog ([#67](https://github.com/hashicorp/terraform-provider-assert/issues/67))
+

README.md

@@ -40,9 +40,7 @@ Test assertions in your Terraform configuration should be simple and easy to rea
 
 ```hcl
 run "ebs_volume_size" {
-
   command = plan
-
   assert {
     condition     = provider::assert::between(1, 100, aws_ebs_volume.example.size)
     error_message = "EBS volume size must be between 1 and 100 GiB"

docs/functions/between.md

@@ -9,13 +9,13 @@ description: |-
 
 
 
+The numeric function `between` returns `true` if the given value is between the two provided values, inclusive of the lower the upper bound. Otherwise, it returns `false`.
+
 ## Terraform Test Example
 
 ```terraform
 run "ebs_volume_size" {
-
   command = plan
-
   assert {
     condition     = provider::assert::between(1, 100, aws_ebs_volume.example.size)
     error_message = "EBS volume size must be between 1 and 100 GiB"

docs/functions/cidr.md

@@ -1,6 +1,6 @@
 ---
 page_title: "cidr function - terraform-provider-assert"
-subcategory: "CIDR Address Functions"
+subcategory: "Network Functions"
 description: |-
   Checks whether a string is a valid CIDR notation (IPv4 or IPv6)
 ---
@@ -9,13 +9,17 @@ description: |-
 
 
 
+The network function `cidr` returns `true` if the provided CIDR range is a valid CIDR notation, regardless of whether it’s IPv4 or IPv6; otherwise, it returns `false`.
+
+It parses the `prefix` as a CIDR notation IP address and prefix length, such as “192.0.2.0/24” or “2001:db8::/32,” as defined in RFC 4632 and RFC 4291.
+
+To validate a CIDR range for a specific IP version, use the `cidrv4` or `cidrv6` functions.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_valid_ip_aws_subnet" {
-
   command = plan
-
   assert {
     condition     = provider::assert::cidr(aws_subnet.example.cidr_block)
     error_message = "Subnet is not in valid CIDR notation"

docs/functions/cidrv4.md

@@ -1,6 +1,6 @@
 ---
 page_title: "cidrv4 function - terraform-provider-assert"
-subcategory: "CIDR Address Functions"
+subcategory: "Network Functions"
 description: |-
   Checks whether a string is a valid CIDR notation (IPv4)
 ---
@@ -9,13 +9,17 @@ description: |-
 
 
 
+The network function `cidrv4` returns true if the provided CIDR range is a valid IPv4 CIDR notation. Otherwise, it returns `false`.
+
+It parses the `prefix` as a CIDR notation IP address and prefix length, such as “192.0.2.0/24” as defined in RFC 4632.
+
+To validate a CIDR range regardless of the IP version, use the `cidr` function.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_valid_ipv4_aws_subnet" {
-
   command = plan
-
   assert {
     condition     = provider::assert::cidrv4(aws_subnet.example.cidr_block)
     error_message = "Subnet is not in valid IPv4 CIDR notation"

docs/functions/cidrv6.md

@@ -1,6 +1,6 @@
 ---
 page_title: "cidrv6 function - terraform-provider-assert"
-subcategory: "CIDR Address Functions"
+subcategory: "Network Functions"
 description: |-
   Checks whether a string is a valid CIDR notation (IPv6)
 ---
@@ -9,13 +9,17 @@ description: |-
 
 
 
+The network function `cidrv6` returns true if the provided CIDR range is a valid IPv6 CIDR notation. Otherwise, it returns `false`.
+
+It parses the `prefix` as a CIDR notation IP address and prefix length, such as “2001:db8::/32,” as defined in RFC 4291.
+
+To validate a CIDR range regardless of the IP version, use the `cidr` function.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_valid_ipv6_aws_subnet" {
-
   command = plan
-
   assert {
     condition     = provider::assert::cidrv6(aws_subnet.example.ipv6_cidr_block)
     error_message = "Subnet is not in valid IPv6 CIDR notation"

docs/functions/contains.md

@@ -9,13 +9,13 @@ description: |-
 
 
 
+The list function `contains` returns `true` if the given value is in the provided list. Otherwise, it returns `false`.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_example_subnet_cidr_block" {
-
   command = plan
-
   assert {
     condition     = provider::assert::contains(cidrsubnets("10.1.0.0/16", 4, 4, 8, 4), aws_subnet.example.cidr_block)
     error_message = "CIDR block is not in the list of allowed subnets"

docs/functions/empty.md

@@ -9,33 +9,22 @@ description: |-
 
 
 
+The string function `empty` returns `true` if the given string is empty. Otherwise, it returns `false`.
+
+A string is considered empty if it is initialized as an empty string and is not null; strings that contain only whitespace characters are not considered empty.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_cloudwatch_log_subscription_match_all" {
-
   command = plan
-
   assert {
     condition     = provider::assert::empty(aws_cloudwatch_log_subscription_filter.example.filter_pattern)
     error_message = "CloudWatch log subscription filter pattern must be empty, as it is a match all."
   }
 }
 ```
 
-## Variable Validation Example
-
-```terraform
-variable "example" {
-  type = string
-
-  validation {
-    condition     = provider::assert::empty(var.example)
-    error_message = "Variable 'example' must be empty."
-  }
-}
-```
-
 ## Signature
 
 <!-- signature generated by tfplugindocs -->

docs/functions/ends_with.md

@@ -9,13 +9,13 @@ description: |-
 
 
 
+The string function `ends_with` returns true if the given string ends with the provided suffix. Otherwise, it returns `false`.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_events_path_google_pubsub_subscription_push_endpoint" {
-
   command = plan
-
   assert {
     condition     = provider::assert::ends_with("/events", google_pubsub_subscription.example.push_config.push_endpoint)
     error_message = "Push endpoint must end with /events"

docs/functions/equal.md

@@ -9,13 +9,13 @@ description: |-
 
 
 
+The numeric function `equal` returns `true` if the given values are equal. Otherwise, it returns `false`.
+
 ## Terraform Test Example
 
 ```terraform
 run "number_of_glue_job_workers_is_5" {
-
   command = plan
-
   assert {
     condition     = provider::assert::equal(5, aws_glue_job.example.number_of_workers)
     error_message = "Number of Glue job workers must be 5"

docs/functions/expired.md

@@ -9,6 +9,8 @@ description: |-
 
 
 
+The time function `expired` checks whether a given timestamp, provided in RFC3339 format, has passed. It returns `true` if the timestamp represents a time that is earlier than the current time. Otherwise, it returns `false`.
+
 ## Continuous Validation Example (AWS)
 
 ```terraform

docs/functions/false.md

@@ -9,13 +9,13 @@ description: |-
 
 
 
+The boolean function `false` returns `true` if the specified value or expression evaluates to `false`; otherwise, it returns `false`.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_rds_global_cluster_deletion_protection" {
-
   command = plan
-
   assert {
     condition     = provider::assert::false(aws_rds_global_cluster.example.deletion_protection)
     error_message = "Cluster deletion protection must be false, this is a dev environment"

docs/functions/greater.md

@@ -9,13 +9,13 @@ description: |-
 
 
 
+The numeric function `greater` returns `true` if the second value is greater than the first value. Otherwise, it returns `false`.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_aws_db_instance_size" {
-
   command = plan
-
   assert {
     condition     = provider::assert::greater(100, aws_db_instance.example.instance_class)
     error_message = "DB instance size must be greater than 100"

docs/functions/greater_or_equal.md

@@ -9,13 +9,13 @@ description: |-
 
 
 
+The numeric function `greater_or_equal` returns `true` if the second value is greater than or equal to the first value. Otherwise, it returns `false`.
+
 ## Terraform Test Example
 
 ```terraform
 run "check_aws_db_instance_size" {
-
   command = plan
-
   assert {
     condition     = provider::assert::greater_or_equal(100, aws_db_instance.example.instance_class)
     error_message = "DB instance size must be greater than or equal to 100"

docs/functions/http_client_error.md

@@ -9,13 +9,15 @@ description: |-
 
 
 
+The HTTP status code function `http_client_error` returns `true` if the given HTTP status code is a client error status code (4xx). Otherwise, it returns `false`.
+
+This function checks against the HTTP status codes defined in the Go standard library [net/http](https://golang.org/pkg/net/http/) package. For details, refer to [src/net/http/status.go](https://cs.opensource.google/go/go/+/refs/tags/go1.23.1:src/net/http/status.go;l=9).
+
 ## Terraform Test Example
 
 ```terraform
 run "check_http_client_error" {
-
   command = plan
-
   assert {
     condition     = provider::assert::http_client_error(data.http.secured.status_code)
     error_message = "My secure website must return an HTTP client error status code"

docs/functions/http_redirect.md

@@ -9,13 +9,15 @@ description: |-
 
 
 
+The HTTP status code function `http_redirect` returns `true` if the given HTTP status code is a redirect status code (3xx). Otherwise, it returns `false`.
+
+This function checks against the HTTP status codes defined in the Go standard library [net/http](https://golang.org/pkg/net/http/) package. For details, refer to [src/net/http/status.go](https://cs.opensource.google/go/go/+/refs/tags/go1.23.1:src/net/http/status.go;l=9).
+
 ## Terraform Test Example
 
 ```terraform
 run "check_http_redirect" {
-
   command = plan
-
   assert {
     condition     = provider::assert::http_redirect(data.http.hashicorp.status_code)
     error_message = "HashiCorp's website must return a 3xx status code, when using HTTP instead of HTTPS"

docs/functions/http_server_error.md

@@ -9,13 +9,15 @@ description: |-
 
 
 
+The HTTP status code function `http_server_error` returns `true` if the given HTTP status code is a server error status code (5xx). Otherwise, it returns `false`.
+
+This function checks against the HTTP status codes defined in the Go standard library [net/http](https://golang.org/pkg/net/http/) package. For details, refer to [src/net/http/status.go](https://cs.opensource.google/go/go/+/refs/tags/go1.23.1:src/net/http/status.go;l=9).
+
 ## Terraform Test Example
 
 ```terraform
 run "check_http_server_error" {
-
   command = plan
-
   assert {
     condition     = provider::assert::http_client_error(data.http.down.status_code)
     error_message = "My down website must return an HTTP server error status code"

docs/functions/http_success.md

@@ -9,13 +9,15 @@ description: |-
 
 
 
+The HTTP status code function `http_success` returns `true` if the given HTTP status code is a success status code (2xx). Otherwise, it returns `false`.
+
+This function checks against the HTTP status codes defined in the Go standard library [net/http](https://golang.org/pkg/net/http/) package. For details, refer to [src/net/http/status.go](https://cs.opensource.google/go/go/+/refs/tags/go1.23.1:src/net/http/status.go;l=9).
+
 ## Terraform Test Example
 
 ```terraform
 run "check_http_success" {
-
   command = plan
-
   assert {
     condition     = provider::assert::http_success(data.http.hashicorp.status_code)
     error_message = "HashiCorp's website must return a 2xx status code"

docs/functions/ip.md

@@ -1,6 +1,6 @@
 ---
 page_title: "ip function - terraform-provider-assert"
-subcategory: "IP Address Functions"
+subcategory: "Network Functions"
 description: |-
   Checks whether a string is a valid IP address (IPv4 or IPv6)
 ---
@@ -9,13 +9,15 @@ description: |-
 
 
 
+The network function `ip` returns `true` if the given string is a valid IP address (either IPv4 or IPv6); otherwise, it returns `false`.
+
+A valid `ip_address` must be represented in one of the following formats: IPv4 dotted decimal (e.g., “192.0.2.1”), standard IPv6 notation (e.g., “2001:db8::68”), or IPv4-mapped IPv6 format (e.g., “::ffff:192.0.2.1”).
+
 ## Terraform Test Example
 
 ```terraform
 run "check_valid_ip_google_compute_address" {
-
   command = plan
-
   assert {
     condition     = provider::assert::ip(google_compute_address.example.address)
     error_message = "Address is not a valid IP address"