docs: add more information about BLOB values in structures

[kuhe]

aws/aws-sdk-js-v3#5240

The PR improves the inline documentation generated for structural hints for operation inputs and outputs.

It differentiates between input and output of the same Smithy type (BLOB). For TypeScript, the inputs are wider than a single type for convenience, and the output has mixin methods attached, again for user convenience.

For a sample diff, see first commit in aws/aws-sdk-js-v3#5864

Examples

output side

STREAMING_BLOB_VALUE

* // { // GetObjectOutput
* //   Body: "STREAMING_BLOB_VALUE",
* //   DeleteMarker: true || false,

becomes

* // { // GetObjectOutput
* //   Body: "<SdkStream>", // see @smithy/types -> StreamingBlobPayloadOutputTypes
* //   DeleteMarker: true || false,

BLOB_VALUE

 * //   Payload: { // SelectObjectContentEventStream Union: only one key present
 * //     Records: { // RecordsEvent
 * //       Payload: "BLOB_VALUE",
 * //     },

becomes

 * //   Payload: { // SelectObjectContentEventStream Union: only one key present
 * //     Records: { // RecordsEvent
 * //       Payload: new Uint8Array(),
 * //     },

---

input side

STREAMING_BLOB_VALUE

 *   Body: "STREAMING_BLOB_VALUE",
 *   Bucket: "STRING_VALUE", // required
 *   CacheControl: "STRING_VALUE",

becomes

 *   Body: "MULTIPLE_TYPES_ACCEPTED", // see @smithy/types -> StreamingBlobPayloadInputTypes
 *   Bucket: "STRING_VALUE", // required
 *   CacheControl: "STRING_VALUE",

BLOB_VALUE

 *   RawMessage: { // RawMessage
 *     Data: "BLOB_VALUE", // required
 *   },

becomes

 *   RawMessage: { // RawMessage
 *     Data: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")     // required
 *   },

[syall]

I think it's better to define isInput from where generateStructuralHintDocumentation() is called.

This is mostly because I'm unsure if smithy-typescript applies input / output traits if the corresponding structures are missing the traits.

smithy-typescript/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptClientCodegenPlugin.java

Lines 69 to 71 in 9275e12

	// TODO: Not using below because it would break existing AWS SDKs. Maybe it should be configurable
	// so generic SDKs call this by default, but AWS SDKs can opt-out of it via a setting.
	// runner.createDedicatedInputsAndOutputs();

Just to be safe, I think it's better to pass in the isInput boolean at these locations:

• Input:

  smithy-typescript/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java

  Lines 213 to 215 in 9275e12

  	+ String.format("const input = %s%n",
  	StructureExampleGenerator.generateStructuralHintDocumentation(
  	model.getShape(operation.getInputShape()).get(), model, false))

• Output:

  smithy-typescript/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java

  Lines 218 to 220 in 9275e12

  	+ String.format("%s%n",
  	StructureExampleGenerator.generateStructuralHintDocumentation(
  	model.getShape(operation.getOutputShape()).get(), model, true))