[Bug] @returnsDoc does not work for ARM templates

Azure / typespec-azure

About TypeSpec Azure Libraries

https://azure.github.io/typespec-azure/

MIT License

11 stars 36 forks source link

[Bug] @returnsDoc does not work for ARM templates #47

Open allenjzhang opened 8 months ago

allenjzhang commented 8 months ago

Describe the bug @returnsDoc does not work for ARM templates. Confirmed working for Azure.Core.

To Reproduce Steps to reproduce the behavior:

allenjzhang commented 6 months ago

The default response description resolution order is taking @doc over @returnsDoc. Since ARM library default supplies @doc for all responses, they could not be overwritten by @returnsDoc. See playground.

In http, it is assumed @doc on response are not used in libraries and explicitly coded the order @doc > @returnsDoc/@errorsDoc > default status code msg. There is a conflict we need to resolve.

allenjzhang commented 6 months ago

Given today @returnsDoc, @errorsDoc does not take in a status code, we could only override all success or all failure with the same doc string. An improvement can be to take an optional status code for targeted overwrite. This can be a design issue for consensus.