Field documentation should include complex specification requirements #457

What happened?

First reported in crossplane-contrib/provider-upjet-aws#1498.

Upjet-generated field documentation omits field specification requirements. For instance AWS RDS's timezone Terraform documentation reads:

timezone - (Optional) Time zone of the DB instance. timezone is currently only supported by Microsoft SQL Server. The timezone can only be set on creation. See MSSQL User Guide for more information.

Corresponding Upjet-generated documentation omits “(Optional)”:

Time zone of the DB instance. timezone is currently only supported by Microsoft SQL Server. The timezone can only be set on creation. See MSSQL User Guide for more information.

Doing so is understandable, because OpenAPIV3 schema contains required field to indicate specification requirements. Tools that generate human readable documentation, such as Upbound Marketplace, could render the specification requirements as they please.

However, there are cases where the specification requirement is more complex than being optional or required, such as RDS's username:

username - (Required unless a snapshot_identifier or replicate_source_db is provided) Username for the master DB user. Cannot be specified for a replica.

In such cases, users don't have a chance to learn about the requirement until they apply the resource manifest.

As a resolution, we might consider including the parenthesized content if it's different than “Optional” or “Required”.