update http library documentation for `@encode` to explicitly call out encoder intent

[mikekistler]

The "Next" version of the docs for the HTTP library says:

I interpret this to mean that if a TypeSpec definition imports the http library, then any emitter, including the openapi3 emitter, will treat a utcDateTime in a header as rfc7231. For the openapi3 emitter, that means the header will be rendered with "format: http-date-rfc7231", but this is not the behavior I see in the playground.

Playground example

[timotheeguerin]

Yeah the doc is correct, the openapi3 emitter should be fixed.

[timotheeguerin]

I think autorest does it correctly

edit: nvm it doesn't either

[mikekistler]

I think the key concern for me is that this doc is for http library -- not the emitters. I don't think the http library currently does any defaulting of encode values for any type. We could change the openapi3 and autorest emitters to implement this behavior, but it would still be incorrect to document this for the http library.

[timotheeguerin]

I disagree, the http libraries makes some assumption of what the typespec means in many ways. If we have this default then it has to be set by http library. You can’t have every emitter interpret it their own way and then be incompatible with each other.

If we don’t want to have this default at all we can discuss it but as far as I remember dpg emitters already respect this behavior

[mikekistler]

Sorry if I wan't clear. I did not mean to imply that the http library shouldn't do this.

My point was that to make the doc accurate we need to change the http library and not the openapi3 and autorest emitters.

[markcowl]

est: 1

Update documentation to indicate emitters should interprest these values this way

[mikekistler]

Should I open a separate issue to fix the autorest and openapi3 emitters?

[timotheeguerin]

Yeah maybe be good