Missing important upstream documentation related to BucketReplicationConfig

[zbuchheit]

Upstream there is some important documentation that isn't present in our documentation

Note

The existing_object_replication parameter is not supported by Amazon S3 at this time and should not be included in your rule configurations. Specifying this parameter will result in MalformedXML errors. To replicate existing objects, please refer to the Replicating existing objects with S3 Batch Replication documentation in the Amazon S3 User Guide.

This is important to doing replication and can lead users to incorrectly configure the bucket replication and hit an error without a clear direction forward.

[guineveresaenger]

The reason this information is missing is most likely due to the fact that this NOTE is not attached to the rule documentation text, but rather to the subheading where rule's nested types are explained.
Here's where we're getting the Description for rule:

But the NOTE is actually further down, in the subheading for rule:

I believe this is less of a function of NOTE (although there is some opinionated behavior around NOTEs in the bridge) and more a function of the source of the information not being associated correctly. We never parse top-level text from nested block headings into the type Description.

See also: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_function#vpc_config vs https://www.pulumi.com/registry/packages/aws/api-docs/lambda/function/#functionvpcconfig - you notice additionally that in the TF docs many of the the configuration block headers have nice intro paragraphs, none of which show up in the Pulumi docs. I believe that has the same cause.

What to do?

A quick "fix" for this one resource, this one time, is to use DocEditRules to edit the source text and move the NOTE text under the top-level rule description. This is horrifically brittle, as it relies on the upstream source not changing.

Given that this is an issue elsewhere as well, we should make an effort to find and correctly associate extra text. I worry that this is a relatively large/complicated change to docsgen, so this may take some effort.

[guineveresaenger]

I've filed pulumi/pulumi-terraform-bridge#2841 to track the bridge fix.

[pulumi-bot]

This issue has been addressed in PR #5112 and shipped in release v6.68.0.