Better example tooling

[Arithmomaniac]

Many API developer portals (such as readme.com) make heavy use of examples, and it's a huge boon to have compile-type checking on them. But writing them is a bit hard.

I can think of two main places examples can come from:

• Payload first: you already have some JSON (for example, if you're documenting an existing API) and you want to make sure your TypeSpec definition conforms.
  In this case, the migration from e.g. {"my array": []} to #{`my array`: #[]} makes this super tedious in bulk (see Value blocks for simplifying defining nested values #3931). It would be a huge help if there was a CLI command that could take arbitrary JSON and spit out equivalent "value"s.
• Model first: you have a TypeSpec model and are trying to write a definition for it. Unfortunately, there is no templating of the example decorator, so while there is realtime method validation, intellisense gives you no help (asides from general string matching) in defining the example:
  
  It would be great if the type of @example : example could be an inferred T instead of just unknown.

And even after you have examples, the differing tooltip and error messages between different ways of specifying an example is really confusing and sometimes incredibly verbose [Playground]. So much so, I'm not sure I have a concrete "ask" (except #4544 and #4545).

These thoughts are based on the work migrating the Sefaria spec; they have hundreds of examples which (see #3866) were manually migrated.

[timotheeguerin]

we talked about that when doing example, we do have a gap in the language to be able to represent that, decided to hold on it for now but I do agree this would be really nice.

[timotheeguerin]

sorry referring the the completion.

For the other part I think what we might be able to do is

1. If its just simple primitive types and hte only problem is the missing # we could maybe make the code fix act recursively so you
2. If its about converting a string date to utcDateTime.fromIso this might be a bit more complex and not sure how we can provide a generic solution to that.

[Arithmomaniac]

It's not just the missing #: you have to convert the string keys too.

The code fix turns

@example({"Baz": "Hello"})
model FooBar { Baz : string; }

into #{"Baz": "Hello"}, but that's not good enough:

Property 'Baz' is missing on type '{ <missing identifier>2: "Baz", <missing identifier>3: "Hello" }' but required in 'FooBar'
TypeSpec(missing-property)

It needs to be recognized as JSON and turned into #{Baz: "Hello"}.

I wouldn't let dealing with (2) prevent a fix to that, or (1).

[Arithmomaniac]

@timotheeguerin would you like me to refile that last comment as a feature request?

[timotheeguerin]

yeah

[Arithmomaniac]

Alright, see #4612 and #4613

[Arithmomaniac]

At this point, about everything actionable has an issue created for it.