Indicate actual input types

[danielrbradley]

Problem description

When looking up input types it looks in the documentation it is confusing that they don't have the indicate which are pulumi.Input<T> vs raw T types.

For example these two input args:

are defined in the Typescript SDK as:

    data?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;

    immutable?: pulumi.Input<boolean>;

Therefore the missing information in the docs is that both properties can come from another output, however, the key within the data record cannot be an output.

Suggestions for a fix

We could add a language specific type definition for each property somewhere e.g. below the simple definition or in the description, which changes based on the user's preferred language. This could also be hidden until revealed if it makes things too messy?

Property	Description
data {[key: string]: string} Typescript: data?: pulumi.Input<{[key: string]: pulumi.Input<string>}>;	Data contains the data.

Alternatively we could expose the whole args type definition in a language switcher with the current table display as the default. For example the headings could be:

Description	Typescript	Python	Go	C#

[susanev]

@danielrbradley is this a dup of https://github.com/pulumi/registry/issues/603? or are these distinct?

[danielrbradley]

No, this is different - rather than the token for the resource type - this is showing the actual types for args (what's passed into a resource) that will be rendered in a specific language's SDK.

This might however be better suited for the registry repo as (I guess) that's where it's implemented?

[lukehoban]

This is different from https://github.com/pulumi/registry/issues/603.

Note that I’m not certain we have to fix this via making the Input aspect explicit on every property. I could imagine a few other fixes:

1. Make prompt inputs explicit (they are much more rare, so less noisy to do this)
2. Find a way to annotate the plain or not aspect as a bit, possibly via a glyph, and have the glyph have hover text that provides more details.
3. Include a note at the top of the table that links to docs on Inputs.
4. etc.

We might want to be as explicit as the original suggestion here, but throwing out some other options in case that explicitness ends up being too noisy (which was the reason we intentionally didn’t do this originally - and the only reason we really now have to do this is that there exist “plain” inputs that didn’t exist before).

[lukehoban]

This might however be better suited for the registry repo as (I guess) that's where it's implemented?

The implementation is actually in https://github.com/pulumi/pulumi/tree/master/pkg/codegen/docs.

[mikhailshilkov]

Who owns the triage of docs? This issue is in "needs-triage" for a week now.

[cnunciato]

Agree this can be confusing. I'd probably suggest we start by seeing how noisy it'd be to have the types be explicit, since that'd probably be the most clear, and then explore alternatives if that doesn't work out.

If anyone's up for taking this on, I'd appreciate it -- otherwise, I can put it on the Content board (I'm generally triaging all website-related issues, but didn't triage this one as there was conversation happening on it), but I do have a few things queued up at the moment that'll make it hard to get to it for a little bit.