From 814130a7f2132fc094bf657d7b4717b1c47e9147 Mon Sep 17 00:00:00 2001
From: Sebastian Rivera <sebastian.rivera@hashicorp.com>
Date: Mon, 28 Oct 2024 15:56:08 -0400
Subject: [PATCH] Clarify documentation, add usage & example output sections

---
 website/docs/cli/commands/modules.mdx | 63 +++++++++++++++++++++++++--
 1 file changed, 59 insertions(+), 4 deletions(-)

diff --git a/website/docs/cli/commands/modules.mdx b/website/docs/cli/commands/modules.mdx
index b957a98b95ae..94514a43b944 100644
--- a/website/docs/cli/commands/modules.mdx
+++ b/website/docs/cli/commands/modules.mdx
@@ -1,17 +1,72 @@
 ---
 page_title: 'Command: modules'
 description: >-
-  The terraform modules command prints information about all the declared
+  The terraform modules command prints source and version data about all declared
   modules in Terraform configuration.
 ---
 
 # Command: modules
 
 The `terraform modules` command provides a holistic view of all Terraform
-modules and their resolved versions that have been declared in Terraform
-configuration for the current working directory.
+modules declared in Terraform configuration for the current working directory.
+This can be useful for auditing or policy purposes on module consumption. The
+output will include a list of each declared module's key, source and version.
+
+-> `terraform modules` requires **Terraform v1.10.0 or later**.
 
 ## Usage
 
-Usage: `terraform modules -json`
+Usage: `terraform modules [options]`
+
+The following flags are available:
+
+- `-json` - Displays the module declarations in a machine-readable, JSON format.
+
+Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options.
+
+The output includes a `format_version` key, which as of Terraform 1.10.0 has
+value `"1.0"`. The semantics of this version are:
+
+- We will increment the minor version, e.g. `"1.1"`, for backward-compatible
+  changes or additions. Ignore any object properties with unrecognized names to
+  remain forward-compatible with future minor versions.
+- We will increment the major version, e.g. `"2.0"`, for changes that are not
+  backward-compatible. Reject any input which reports an unsupported major
+  version.
+
+We will introduce new major versions only within the bounds of
+[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises).
+
+## Output Format
+
+The following section describes the JSON output format by example, using a pseudo-JSON notation.
+
+```javascript
+{
+    "format_version": "1.0",
+    "modules": [
+        {
+            "key": "my_local_module",
+            "source": "./path/to/local/module",
+            "version": ""
+        },
+        {
+            "key": "my_private_registry_module",
+            "source": "app.terraform.io/hashicorp/label/null",
+            "version": "1.0.0"
+        },
+        {
+            "key": "my_public_registry_module",
+            "source": "terraform-aws-modules/iam/aws",
+            "version": "5.47.1"
+        },
+        {
+            "key": "my_remote_module",
+            "source": "https://example.com/vpc-module.zip",
+            "version": ""
+        }
+    ]
+}
+```
+