Review inlining and naming choices in OpenAPI

[nguerrera]

#463 refactors how we decide what to inline and what names to use and puts it all in one place, but it doesn't change behavior except to fix obvious bugs.

EDIT See first comment for proposal.

---

Bit of a brain dump here. I will think on it and try to build a proposal.

Briefly, we currently:

• Inline anonymous types, including arrays, tuples, anonymous unions, anonymous models, etc.
• Inline template instantiations with no @friendlyName,
• We effectively provide a default @friendlyName of Type_Arg1_...ArgN if the args are not inlined and not themselves template instantiations.
• Strip off root Cadl and service namespace

Issues:

• friendlyName drops namespace
• friendlyName can easily cause collisions (we will now produce an error if there's a collision)
• Weird that Foo<string> is inlined but Foo<Bar<string>> is not (absent any explicit friendly names). This feels like the sort of quirk that will bite us when we go to change it and break someone.
• Stripping Cadl alone still leaves lots of Rest.*. Maybe the namespaces to filter should be bigger and/or configurable, or maybe we should filter all namespaces unless there's a collision?
• It's not really possible to use friendlyName with more than one type parameter. How do you refer to more than one name?
• We report duplicate type names but only on the occurrences after the initial occurence. We should report all occurences as we do for symbols and endpoints. We should also consider along above lines if we can make collisions less likely or impossible in certain cases where they can occur today.

[nguerrera]

Proposal:

1. Drop full qualification with namespace unless there is an actual collision. This might be tricky to implement, but I think it gives the cleanest experience.

2. Append namespace to friendly name also if friendly name collides. Friendly name collisions are still possible in other cases (say two types in same namespace with same friendly name). Fix the error reporting we have laready to report both locations that caused a collision, but keep the

3. Remove default friendly name with underscores. The conditions where we do this are, IMHO, too fragile and complex. We should do one of two things instead:
   a. Inline templates unless they have a friendly name.
   b. Emit template instantiations with angle brackets and URL-encoded refs.

I could go either way on these. In both cases, people will dislike the emit sometimes but model is and @friendlyName allow the user to override things to their liking. For completeness of user control, consider adding an @inline decorator that the user can use to force inlining if we choose (b).

4. Augment the syntax for decorators with string substitutions to allow referencing more than one argument.

@friendlyName("Map{0:name}To{1:name}", K, V)
model Map<K, V>`

This can be made backwards compatible, if there is no ':' '0:' is implied. We could also consider allowing {<number>} as being equivalent to {<number>:name} since .name property is the overwhelmingly common case and then you could also do @friendlyName("Map{0}To{1}, K, V).

Also disallow undefined property just formatting into the name as undefined with a proper diagnostic.

[nguerrera]

Filed #562 to do 3a, which was the only conclusion in the design meeting today. We will need to re-discuss the other points in a future design meeting.

[markcowl]

Need to still decide 1, 2, and 4 design