diff --git a/.terraform-docs.yaml b/.terraform-docs.yaml
index 321eb60..281dfee 100644
--- a/.terraform-docs.yaml
+++ b/.terraform-docs.yaml
@@ -26,7 +26,20 @@ content: |-
 
   {{ .Providers }}
 
-  {{ .Resources }}
+  ## Resources
+  | Name | Type |
+  |------|------|
+  {{- range .Module.Resources }}
+  {{- $isResource := and $.Config.Sections.Resources (eq "resource" (printf "%s" .GetMode)) }}
+  {{- $isDataResource := and $.Config.Sections.DataSources (eq "data source" (printf "%s" .GetMode)) }}
+  {{- if or $isResource $isDataResource }}
+  {{- $fullspec := ternary .URL (printf "[%s](%s)" .Spec .URL) .Spec }}
+  | {{ $fullspec }} | {{ .GetMode }} |
+  {{- if .Description }}
+  |**Description:** {{  tostring .Description | sanitizeMarkdownTbl   }} ||
+  {{- end }}
+  {{- end }}
+  {{- end }}
 
   {{ .Inputs }}
 
diff --git a/codeartifact-repo/README.md b/codeartifact-repo/README.md
index 6b2062a..cc8cb65 100644
--- a/codeartifact-repo/README.md
+++ b/codeartifact-repo/README.md
@@ -15,8 +15,8 @@ This module is intended to configure AWS CodeArtifact domains and repositories.
 
 | Name | Version |
 |------|---------|
-| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | ~> 1.14.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 6.21.0 |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | => 1.14.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | => 6.21.0 |
 
 ## Providers
 
@@ -25,20 +25,30 @@ This module is intended to configure AWS CodeArtifact domains and repositories.
 | <a name="provider_aws"></a> [aws](#provider\_aws) | 6.21.0 |
 
 ## Resources
-
 | Name | Type |
 |------|------|
 | [aws_codeartifact_domain.repo_domain](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/codeartifact_domain) | resource |
+|**Description:** CodeArtifact domain acting as a container for repositories ||
 | [aws_codeartifact_domain_permissions_policy.domain_permissions_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/codeartifact_domain_permissions_policy) | resource |
+|**Description:** Optional  permissions policy applied to the created domain. Only created if a policy document path is provided. ||
 | [aws_codeartifact_repository.repository](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/codeartifact_repository) | resource |
+|**Description:** CodeArtifact repositories within the domain. Multiple repositories can be created by providing a list of repository configurations, ||
 | [aws_codeartifact_repository_permissions_policy.repo_permissions_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/codeartifact_repository_permissions_policy) | resource |
+|**Description:** Optional permissions policy applied to each repository. Only created if a policy document path is provided in the repository configuration. ||
 | [aws_iam_role.admin_access_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
+|**Description:** IAM role for admin access to domain and repositories. This should be assumed by the provided admin principals. Not created if no admin principals are provided. ||
 | [aws_iam_role.publisher_access_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
+|**Description:** IAM role for publisher access to domain and repositories. This should be assumed by the provided publisher principals. Not created if no publisher principals are provided. Publishers are allowed to publish packages in addition to read-only access. ||
 | [aws_iam_role.read_access_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
+|**Description:** IAM role for read-only access to domain and repositories. This should be assumed by the provided reader principals. Not created if no reader principals are provided. ||
 | [aws_iam_role_policy.admin_access_role_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy) | resource |
+|**Description:** IAM policy attaching admin permissions to the admin access role. Not created if no admin principals are provided. ||
 | [aws_iam_role_policy.publisher_access_role_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy) | resource |
+|**Description:** IAM policy attaching publisher permissions to the publisher access role. Not created if no publisher principals are provided. ||
 | [aws_iam_role_policy.read_only_role_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy) | resource |
+|**Description:** IAM policy attaching read-only permissions to the read access role. Not created if no reader principals are provided. ||
 | [aws_kms_key.domain_encryption_key](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_key) | resource |
+|**Description:** Optional KMS key for domain encryption. Created only if no encryption key ARN is provided and default encryption key usage is disabled. ||
 
 ## Inputs
 
@@ -68,4 +78,43 @@ This module is intended to configure AWS CodeArtifact domains and repositories.
 | <a name="output_policy_documents"></a> [policy\_documents](#output\_policy\_documents) | A map of repository names to their applied policy documents (if any). |
 
 ## Examples
+
+Example configuration and usage of this module:
+
+```hcl
+module "my_repo" {
+    # use repo URL as module source
+    source = "https://github.com/bitshifted/cloud-tools//codeartifact-repo?ref=codeart-fact-repo-<current version>"
+
+    # domain name to be used for domain
+    domain_name = "my-domain"
+
+    # don't use AWS default encryption key.
+    use_default_ecnryption_key = false
+    # use this KMS key for encryption. If not specified, new KMS key will be created
+    encryption_key_arn = "arn:aws::/keys/1233"
+
+    # IAM principals specified here will have read access to repositories, ie. able to pull paclages
+    reader_principals = [
+    "arn:aws:iam::11111111:user/reader",
+  ]
+  # IAM principals specified here will have write access to repositories, ie. able to publish packages
+  publisher_principals = [
+    "arn:aws:iam::22222222:user/publisher",
+  ]
+
+  repositories = [
+    { 
+        # repository name
+        repository_name = "test-repo-2",
+        # external connection to eg. upstream repository (optional)
+        external_connection = "public:npmjs"
+        # path to policy file that will be applied to repository
+        policy_document_path = "./repo-policy.json"
+     }
+  ]
+}
+    
+}
+```
 <!-- END_TF_DOCS -->
\ No newline at end of file
diff --git a/codeartifact-repo/docs/examples.md b/codeartifact-repo/docs/examples.md
index 4f895f0..0176a80 100644
--- a/codeartifact-repo/docs/examples.md
+++ b/codeartifact-repo/docs/examples.md
@@ -1,2 +1,40 @@
 ## Examples
 
+Example configuration and usage of this module:
+
+```hcl
+module "my_repo" {
+    # use repo URL as module source
+    source = "https://github.com/bitshifted/cloud-tools//codeartifact-repo?ref=codeart-fact-repo-<current version>"
+
+    # domain name to be used for domain
+    domain_name = "my-domain"
+
+    # don't use AWS default encryption key.
+    use_default_ecnryption_key = false
+    # use this KMS key for encryption. If not specified, new KMS key will be created
+    encryption_key_arn = "arn:aws::/keys/1233"
+
+    # IAM principals specified here will have read access to repositories, ie. able to pull paclages
+    reader_principals = [
+    "arn:aws:iam::11111111:user/reader",
+  ]
+  # IAM principals specified here will have write access to repositories, ie. able to publish packages
+  publisher_principals = [
+    "arn:aws:iam::22222222:user/publisher",
+  ]
+
+  repositories = [
+    { 
+        # repository name
+        repository_name = "test-repo-2",
+        # external connection to eg. upstream repository (optional)
+        external_connection = "public:npmjs"
+        # path to policy file that will be applied to repository
+        policy_document_path = "./repo-policy.json"
+     }
+  ]
+}
+    
+}
+```
\ No newline at end of file
diff --git a/codeartifact-repo/main.tf b/codeartifact-repo/main.tf
index 893f185..3e6bdcb 100644
--- a/codeartifact-repo/main.tf
+++ b/codeartifact-repo/main.tf
@@ -9,6 +9,7 @@ locals {
 
 data "aws_caller_identity" "current" {}
 
+# CodeArtifact domain acting as a container for repositories
 resource "aws_codeartifact_domain" "repo_domain" {
   domain         = var.domain_name
   region         = var.repo_region != null ? var.repo_region : null
@@ -16,6 +17,7 @@ resource "aws_codeartifact_domain" "repo_domain" {
   tags           = var.tags
 }
 
+# Optional  permissions policy applied to the created domain. Only created if a policy document path is provided.
 resource "aws_codeartifact_domain_permissions_policy" "domain_permissions_policy" {
   count           = var.domain_policy_document_path != null ? 1 : 0
   domain          = aws_codeartifact_domain.repo_domain.domain
@@ -25,6 +27,7 @@ resource "aws_codeartifact_domain_permissions_policy" "domain_permissions_policy
   policy_revision = var.domain_permissions_policy_revision != null ? var.domain_permissions_policy_revision : null
 }
 
+# CodeArtifact repositories within the domain. Multiple repositories can be created by providing a list of repository configurations,
 resource "aws_codeartifact_repository" "repository" {
   for_each     = { for repo in var.repositories : repo.repository_name => repo }
   domain       = aws_codeartifact_domain.repo_domain.domain
@@ -49,7 +52,7 @@ resource "aws_codeartifact_repository" "repository" {
   tags = var.tags
 }
 
-
+# Optional permissions policy applied to each repository. Only created if a policy document path is provided in the repository configuration.
 resource "aws_codeartifact_repository_permissions_policy" "repo_permissions_policy" {
   for_each        = { for repo in var.repositories : repo.repository_name => repo if repo.policy_document_path != null }
   repository      = aws_codeartifact_repository.repository[each.key].repository
@@ -59,6 +62,7 @@ resource "aws_codeartifact_repository_permissions_policy" "repo_permissions_poli
   domain_owner    = each.value.domain_owner != null ? each.value.domain_owner : null
 }
 
+# Optional KMS key for domain encryption. Created only if no encryption key ARN is provided and default encryption key usage is disabled.
 resource "aws_kms_key" "domain_encryption_key" {
   count               = local.should_create_kms_key ? 1 : 0
   description         = "KMS key for CodeArtifact domain ${var.domain_name}"
@@ -186,6 +190,7 @@ data "aws_iam_policy_document" "assume_admin_role_document" {
   }
 }
 
+# IAM role for read-only access to domain and repositories. This should be assumed by the provided reader principals. Not created if no reader principals are provided.
 resource "aws_iam_role" "read_access_role" {
   count              = var.reader_principals != null && length(var.reader_principals) > 0 ? 1 : 0
   name               = "CodeArtifactReadAccessRole-${aws_codeartifact_domain.repo_domain.domain}"
@@ -194,12 +199,15 @@ resource "aws_iam_role" "read_access_role" {
   tags               = var.tags
 }
 
+# IAM policy attaching read-only permissions to the read access role. Not created if no reader principals are provided.
 resource "aws_iam_role_policy" "read_only_role_policy" {
   count  = var.reader_principals != null && length(var.reader_principals) > 0 ? 1 : 0
   policy = data.aws_iam_policy_document.read_only_policy_document[0].json
   role   = aws_iam_role.read_access_role[0].name
 }
 
+# IAM role for publisher access to domain and repositories. This should be assumed by the provided publisher principals. Not created if no publisher principals are provided.
+# Publishers are allowed to publish packages in addition to read-only access.
 resource "aws_iam_role" "publisher_access_role" {
   count              = var.publisher_principals != null && length(var.publisher_principals) > 0 ? 1 : 0
   name               = "CodeArtifactPublisherAccessRole-${aws_codeartifact_domain.repo_domain.domain}"
@@ -208,12 +216,14 @@ resource "aws_iam_role" "publisher_access_role" {
   tags               = var.tags
 }
 
+# IAM policy attaching publisher permissions to the publisher access role. Not created if no publisher principals are provided.
 resource "aws_iam_role_policy" "publisher_access_role_policy" {
   count  = var.publisher_principals != null && length(var.publisher_principals) > 0 ? 1 : 0
   policy = data.aws_iam_policy_document.publisher_policy_document[0].json
   role   = aws_iam_role.publisher_access_role[0].name
 }
 
+# IAM role for admin access to domain and repositories. This should be assumed by the provided admin principals. Not created if no admin principals are provided.
 resource "aws_iam_role" "admin_access_role" {
   count              = var.admin_principals != null && length(var.admin_principals) > 0 ? 1 : 0
   name               = "CodeArtifactAdminAccessRole-${aws_codeartifact_domain.repo_domain.domain}"
@@ -222,6 +232,7 @@ resource "aws_iam_role" "admin_access_role" {
   tags               = var.tags
 }
 
+# IAM policy attaching admin permissions to the admin access role. Not created if no admin principals are provided.
 resource "aws_iam_role_policy" "admin_access_role_policy" {
   count  = var.admin_principals != null && length(var.admin_principals) > 0 ? 1 : 0
   policy = data.aws_iam_policy_document.admin_policy_document[0].json
diff --git a/codeartifact-repo/providers.tf b/codeartifact-repo/providers.tf
index b5d5565..cd6a56b 100644
--- a/codeartifact-repo/providers.tf
+++ b/codeartifact-repo/providers.tf
@@ -2,11 +2,11 @@
 # SPDX-License-Identifier: MPL-2.0
 
 terraform {
-  required_version = "~> 1.14.0"
+  required_version = ">= 1.14.0"
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = "~> 6.21.0"
+      version = ">= 6.21.0"
     }
   }
 }
\ No newline at end of file