StackReference getOutputDetails example is misleading

[joeduffy]

The StackReference docs for getOutputDetails seem wrong/misleading.

Namely, this part:

On the other hand, as an example of using getOutputDetails, suppose that your referenced stack creates a VPC and exports a list of public subnets as a JSON-serialized string, and you want to add a bastion host to each subnet.

This is not what I'm seeing. If I export an array of subnet IDs from my program, and then fetch them in another stack with getOutputDetails, I get back an array, not a string. I was misled into assuming getOutputDetails would simply return those as a string, but it seems to automatically parse them.

After re-reading the docs, I see that it says "exports a list of public subnets as a JSON-serialized string"; so I guess they docs aren't technically incorrect. However, (a) most people wouldn't go out of their way to JSON serialize their stack outputs (they'd just output them) and (b) we should make it clear that if you export structured objects, their type will automatically round trip without you needing to do anything.

(Assuming that is correct -- given the docs, I am not sure!)

I am also unsure if this is true universally across all supported languages. I would hope so.