Bugfix within shorthand example generation for map-type parameters in documentation

[aemous]

Related Issues:

• SQS Message Attributes Shorthand error #3637 - sqs send-message
• SNS publiish documentation incorrect #5129 - sns publish
• iot update-event-configurations shorthand syntax mismatch between docs and actual functionality #7433 - iot update-event-configurations

Description of changes:

• When parameter-type is map, and the value is a structure or list, include curly-braces or square-brackets around the value. This change is consistent with how structures are handled.
• Increased the max stack size from 3 to 4. This threshold controls which parameters receive a generated shorthand example. Without this increase, 61 shorthand examples would have been removed from the docs. As a consequence of this increase, 38 shorthand examples will be added to the docs (see Description of Impact below).

Description of tests:

• Added a new test to verify the behavior of the new code. Ran and passed all tests with a build-and-validate workflow execution.
• Generated a diff of the docs with and without this change. Verified the changes look as expected. Fed the diff to an LLM and prompted it to summarize the diff in human-readable text-only format. I've attached the summaries for in Description of Impact below.
• Verified the updated shorthand syntax examples are correctly rendered in the man pages on Mac OS building from source.

Notes:

This PR supersedes #7286, which did not increase the max stack size to 4, and would have caused 61 shorthand examples for being removed.

Description of impact:

Two files attaches below describe the full set of docs changes that will be caused by this change:

• shorthand_diff_4stack_unique_summary.txt Describes 38 added shorthand syntax examples that reach a max depth of 4.
• shorthand_diff_4stack_summary.txt Describes 127 updated shorthand examples for a parameter type of map.

shorthand_diff_4stack_unique_summary.txt
shorthand_diff_4stack_summary.txt

[aemous]

For reviewer, some of the 38 added shorthand syntax examples are relatively long/complex due to the increase of the max stack-size from 3 to 4. I want to get feedback on this.

For example, below is a shorthand syntax example that will be added to securityhub/create-insight if we merge this as-is. It contains 10,158 characters. For reference, that largest shorthand syntax example currently published is 4,982 characters long, located at https://docs.aws.amazon.com/cli/latest/reference/timestream-influxdb/create-db-parameter-group.html.

My proposal is to implement a second threshold, that prevents shorthand syntax from being generated if it exceeds 5,000 characters. I'm open to adding this to this PR if the code reviewer agrees with this proposal.

Text:

ProductArn=[{Value=string,Comparison=string},{Value=string,Comparison=string}],AwsAccountId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],Id=[{Value=string,Comparison=string},{Value=string,Comparison=string}],GeneratorId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],Region=[{Value=string,Comparison=string},{Value=string,Comparison=string}],Type=[{Value=string,Comparison=string},{Value=string,Comparison=string}],FirstObservedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],LastObservedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],CreatedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],UpdatedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],SeverityProduct=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],SeverityNormalized=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],SeverityLabel=[{Value=string,Comparison=string},{Value=string,Comparison=string}],Confidence=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],Criticality=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],Title=[{Value=string,Comparison=string},{Value=string,Comparison=string}],Description=[{Value=string,Comparison=string},{Value=string,Comparison=string}],RecommendationText=[{Value=string,Comparison=string},{Value=string,Comparison=string}],SourceUrl=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ProductFields=[{Key=string,Value=string,Comparison=string},{Key=string,Value=string,Comparison=string}],ProductName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],CompanyName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],UserDefinedFields=[{Key=string,Value=string,Comparison=string},{Key=string,Value=string,Comparison=string}],MalwareName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],MalwareType=[{Value=string,Comparison=string},{Value=string,Comparison=string}],MalwarePath=[{Value=string,Comparison=string},{Value=string,Comparison=string}],MalwareState=[{Value=string,Comparison=string},{Value=string,Comparison=string}],NetworkDirection=[{Value=string,Comparison=string},{Value=string,Comparison=string}],NetworkProtocol=[{Value=string,Comparison=string},{Value=string,Comparison=string}],NetworkSourceIpV4=[{Cidr=string},{Cidr=string}],NetworkSourceIpV6=[{Cidr=string},{Cidr=string}],NetworkSourcePort=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],NetworkSourceDomain=[{Value=string,Comparison=string},{Value=string,Comparison=string}],NetworkSourceMac=[{Value=string,Comparison=string},{Value=string,Comparison=string}],NetworkDestinationIpV4=[{Cidr=string},{Cidr=string}],NetworkDestinationIpV6=[{Cidr=string},{Cidr=string}],NetworkDestinationPort=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],NetworkDestinationDomain=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ProcessName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ProcessPath=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ProcessPid=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],ProcessParentPid=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],ProcessLaunchedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],ProcessTerminatedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],ThreatIntelIndicatorType=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ThreatIntelIndicatorValue=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ThreatIntelIndicatorCategory=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ThreatIntelIndicatorLastObservedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],ThreatIntelIndicatorSource=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ThreatIntelIndicatorSourceUrl=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceType=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourcePartition=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceRegion=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceTags=[{Key=string,Value=string,Comparison=string},{Key=string,Value=string,Comparison=string}],ResourceAwsEc2InstanceType=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsEc2InstanceImageId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsEc2InstanceIpV4Addresses=[{Cidr=string},{Cidr=string}],ResourceAwsEc2InstanceIpV6Addresses=[{Cidr=string},{Cidr=string}],ResourceAwsEc2InstanceKeyName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsEc2InstanceIamInstanceProfileArn=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsEc2InstanceVpcId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsEc2InstanceSubnetId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsEc2InstanceLaunchedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],ResourceAwsS3BucketOwnerId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsS3BucketOwnerName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsIamAccessKeyUserName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsIamAccessKeyPrincipalName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsIamAccessKeyStatus=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceAwsIamAccessKeyCreatedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],ResourceAwsIamUserUserName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceContainerName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceContainerImageId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceContainerImageName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceContainerLaunchedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],ResourceDetailsOther=[{Key=string,Value=string,Comparison=string},{Key=string,Value=string,Comparison=string}],ComplianceStatus=[{Value=string,Comparison=string},{Value=string,Comparison=string}],VerificationState=[{Value=string,Comparison=string},{Value=string,Comparison=string}],WorkflowState=[{Value=string,Comparison=string},{Value=string,Comparison=string}],WorkflowStatus=[{Value=string,Comparison=string},{Value=string,Comparison=string}],RecordState=[{Value=string,Comparison=string},{Value=string,Comparison=string}],RelatedFindingsProductArn=[{Value=string,Comparison=string},{Value=string,Comparison=string}],RelatedFindingsId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],NoteText=[{Value=string,Comparison=string},{Value=string,Comparison=string}],NoteUpdatedAt=[{Start=string,End=string,DateRange={Value=integer,Unit=string}},{Start=string,End=string,DateRange={Value=integer,Unit=string}}],NoteUpdatedBy=[{Value=string,Comparison=string},{Value=string,Comparison=string}],Keyword=[{Value=string},{Value=string}],FindingProviderFieldsConfidence=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],FindingProviderFieldsCriticality=[{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double},{Gte=double,Lte=double,Eq=double,Gt=double,Lt=double}],FindingProviderFieldsRelatedFindingsId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],FindingProviderFieldsRelatedFindingsProductArn=[{Value=string,Comparison=string},{Value=string,Comparison=string}],FindingProviderFieldsSeverityLabel=[{Value=string,Comparison=string},{Value=string,Comparison=string}],FindingProviderFieldsSeverityOriginal=[{Value=string,Comparison=string},{Value=string,Comparison=string}],FindingProviderFieldsTypes=[{Value=string,Comparison=string},{Value=string,Comparison=string}],Sample=[{Value=boolean},{Value=boolean}],ComplianceSecurityControlId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ComplianceAssociatedStandardsId=[{Value=string,Comparison=string},{Value=string,Comparison=string}],VulnerabilitiesExploitAvailable=[{Value=string,Comparison=string},{Value=string,Comparison=string}],VulnerabilitiesFixAvailable=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ComplianceSecurityControlParametersName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ComplianceSecurityControlParametersValue=[{Value=string,Comparison=string},{Value=string,Comparison=string}],AwsAccountName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceApplicationName=[{Value=string,Comparison=string},{Value=string,Comparison=string}],ResourceApplicationArn=[{Value=string,Comparison=string},{Value=string,Comparison=string}]

According to code comments, there was a long-term plan to create an improved way of displaying complex shorthand syntax.

[hssyoo]

Can we compare diffs between current generated HTML and new to make sure only expected changes are being made?

[hssyoo]

Bugfix looks good, not sure about changing max stack

[hssyoo]

It seems like setting _MAX_STACK to 3 was an intentional choice: #1467

Instead of defining more logic to remove long shorthand syntax if it's over a certain threshold, I'm inclined to just not change _MAX_STACK unless we think there's enough value coming from net-new shorthand syntax docs.

[aemous]

Instead of defining more logic to remove long shorthand syntax if it's over a certain threshold, I'm inclined to just not change _MAX_STACK unless we think there's enough value coming from net-new shorthand syntax docs.

Fair. Just to clarify my original perspective, by making the bugfix so that map adds to the stack, some shorthand syntax that had map as the parameter type will now have a stack size of 4 instead of 3, now causing those to no longer show in docs. Technically these examples always had a stack size of 4 in theory (map + 3 other levels), just that map never added to the stack, so it was actually 3 in practice.

So maybe the 61 shorthand examples that will be removed technically should not have been generated previously. I'll revert to 3 in next revision. Just leaving that context here.