docs/s3: document how object lock configuration works

website/docs/r/s3_bucket.html.markdown

@@ -57,6 +57,12 @@ See the [`aws_s3_bucket_logging` resource](s3_bucket_logging.html.markdown) for
 The `lifecycle_rule` argument is read-only as of version 4.0 of the Terraform AWS Provider.
 See the [`aws_s3_bucket_lifecycle_configuration` resource](s3_bucket_lifecycle_configuration.html.markdown) for configuration details.
 
+### Using object lock configuration
+
+The `object_lock_configuration.rule` argument is read-only as of version 4.0 of the Terraform AWS Provider.
+To **enable** Object Lock on your bucket, use must still use the `object_lock_configuration.object_lock_enabled` argument in **this** resource.
+To configure the default retention rule of the Object Lock configuration, see the [`aws_s3_bucket_object_lock_configuration` resource](s3_bucket_object_lock_configuration.html.markdown) for configuration details.
+
 ### Using replication configuration
 
 The `replication_configuration` argument is read-only as of version 4.0 of the Terraform AWS Provider.
@@ -78,17 +84,20 @@ The following arguments are supported:
 
 * `bucket` - (Optional, Forces new resource) The name of the bucket. If omitted, Terraform will assign a random, unique name. Must be lowercase and less than or equal to 63 characters in length. A full list of bucket naming rules [may be found here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html).
 * `bucket_prefix` - (Optional, Forces new resource) Creates a unique bucket name beginning with the specified prefix. Conflicts with `bucket`. Must be lowercase and less than or equal to 37 characters in length. A full list of bucket naming rules [may be found here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html).
-* `tags` - (Optional) A map of tags to assign to the bucket. If configured with a provider [`default_tags` configuration block](/docs/providers/aws/index.html#default_tags-configuration-block) present, tags with matching keys will overwrite those defined at the provider-level.
 * `force_destroy` - (Optional, Default:`false`) A boolean that indicates all objects (including any [locked objects](https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lock-overview.html)) should be deleted from the bucket so that the bucket can be destroyed without error. These objects are *not* recoverable.
-* `object_lock_configuration` - (Optional) A configuration of [S3 object locking](https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lock.html) (documented below)
+* `object_lock_configuration` - (Optional) A configuration of [S3 object locking](https://docs.aws.amazon.com/AmazonS3/latest/dev/object-lock.html). See [Object Lock Configuration](#object-lock-configuration) below.
+* `tags` - (Optional) A map of tags to assign to the bucket. If configured with a provider [`default_tags` configuration block](/docs/providers/aws/index.html#default_tags-configuration-block) present, tags with matching keys will overwrite those defined at the provider-level.
 
-The `object_lock_configuration` object supports the following:
+### Object Lock Configuration
 
-* `object_lock_enabled` - (Required) Indicates whether this bucket has an Object Lock configuration enabled. Valid value is `Enabled`.
-
-~> **NOTE on `object_lock_configuration`:** You can only enable S3 Object Lock for new buckets. If you need to turn on S3 Object Lock for an existing bucket, please contact AWS Support.
+~> **NOTE:** You can only enable S3 Object Lock for _new_ buckets. If you need to turn on S3 Object Lock for an _existing_ bucket, please contact AWS Support.
 When you create a bucket with S3 Object Lock enabled, Amazon S3 automatically enables versioning for the bucket.
 Once you create a bucket with S3 Object Lock enabled, you can't disable Object Lock or suspend versioning for the bucket.
+To configure the default retention rule of the Object Lock configuration, see the [`aws_s3_bucket_object_lock_configuration` resource](s3_bucket_object_lock_configuration.html.markdown) for configuration details.
+
+The `object_lock_configuration` configuration block supports the following argument:
+
+* `object_lock_enabled` - (Required) Indicates whether this bucket has an Object Lock configuration enabled. Valid value is `Enabled`.
 
 ## Attributes Reference
 

website/docs/r/s3_bucket_object_lock_configuration.html.markdown

@@ -10,10 +10,14 @@ description: |-
 
 Provides an S3 bucket Object Lock configuration resource. For more information about Object Locking, go to [Using S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) in the Amazon S3 User Guide.
 
-~> **NOTE:** You can only enable Object Lock for new buckets. If you want to turn on Object Lock for an existing bucket, contact AWS Support.
+~> **NOTE:** This resource **does not enable** Object Lock for _new_ buckets. It configures a default retention period for objects placed in the specified bucket.
+Thus, to **enable** Object Lock for a _new_ bucket, see the the [`aws_s3_bucket` resource](s3_bucket.html.markdown) or the [following example](#Example-Usage).
+If you want to turn on Object Lock for an _existing_ bucket, contact AWS Support.
 
 ## Example Usage
 
+### Object Lock configuration for a new bucket
+
 ```terraform
 resource "aws_s3_bucket" "example" {
   bucket = "mybucket"