[Metadata] Document end-to-end for emitters

[nguerrera]

There's enough in the REST layer for a different emitter to handle metadata as the openapi emitter does, but it would be nice to have a small walktrhough on that.

[markcowl]

pri: 1
est: 3

[nguerrera]

Also document getEffectiveType here.

[nguerrera]

I have written a sample that calls all of the API. I am still working on cleaning it up and writing doc text to go with it. Work in progress is here: https://gist.github.com/nguerrera/36df0c007be7d37e5e67fd769958030e

Also putting down some rough notes I have on things to cover in the doc text.

Key points:

1. Put properties in models only if they logically belong there. The feature is about allowing logical models + visibility/metadata annotations. It is not about cramming as much as possible into as few types as possible at all cost.

2. Emitters are not required to generate split types, they can emit unified types and use the information about which properties are present in which cases in other ways. For example, serializing to request/from response differently, making property that only appears sometimes nullable in a single type, etc.

API cheat sheet

• getRequestVisibility(HttpVerb): Visibility - use this to determine the visibility implied for data in the request parameters or body. (And note also that Visibility.Read is always applied for response data and therefore there is no corresponding response API.)

• createMetadataInfo(Program) - create this once for each projected program/service version, use it to reason about metadata and visibility implications

• MetadataInfo.getEffectivePayloadType(Type, Visibility): Type - use this on every type that is referenced. if it is an anonymous model sourced entirely from named properties after metadata is moved elsewhere or invisible properties are removed, it will recover the named model that should be used. This handles op foo(...Thing) but also many other cases.

• MetaddataInfo.isTransformed(Type, Visibility): boolean - use this to check if a type undergoes any changes in shape. Can allow for simplifications in emit.

• MetadataInfo.isPayloadProperty(ModelProperty, Visibility): boolean - use this to check if a property is transmitted as an object property (in the payload) and not invisible or metadata sent elsewhere

• Visibility.Item - Add this when recursing into an array. It puts all metadata into payload. Useful in scenarios like batching API calls. This is missing from the main metadata docs as well.

• MetadataInfo.isOptional(ModelProperty, Visibility): boolean. Newly added. Makes properties optional in update operations. Not shown in sample yet, not in main metadata docs yet eiher.