Poor operation template documentation

tjprescott commented 1 year ago

op Azure.Core.ResourceOperations.ResourceCreateOrReplace(apiVersion: string, resource: TResource): (anonymous model) | (anonymous model) | TErrorResponse

Note the two instances of (anonymous model). This isn't helpful for users.

Here is the actual source:

interface ResourceOperations<
  InterfaceTraits,
  TErrorResponse = Azure.Core.Foundations.ErrorResponse
> {
  /**
   * Create or replace operation template.
   * @template TResource Resource type.
   * @template Traits Object describing the traits of the operation.
   */
  @createsOrReplacesResource(TResource)
  ResourceCreateOrReplace<
    TResource extends object,
    Traits extends object = {}
  > is Foundations.ResourceOperation<
    TResource,
    Foundations.ResourceBody<TResource> &
      TraitProperties<
        Traits & InterfaceTraits,
        TraitLocation.Parameters,
        TraitContext.Create | TraitContext.Update
      >,
    Foundations.ResourceCreatedOrOkResponse<TResource &
      TraitProperties<
        Traits & InterfaceTraits,
        TraitLocation.Response,
        TraitContext.Create | TraitContext.Update
      >>,
    Traits & InterfaceTraits,
    TErrorResponse
  >;

Presumably the two anonymous models are the ResourceCreated and OkResponse models.

daviwil commented 1 year ago

This is due to how ResourceCreatedOrOkResponse and its related types are defined:

alias ResourceCreatedResponse<T extends object> = TypeSpec.Http.Response<201> & T;

alias ResourceOkResponse<T> = TypeSpec.Http.Response<200> & T;

alias ResourceCreatedOrOkResponse<T extends object> = ResourceCreatedResponse<T> | ResourceOkResponse<T>;

Because they're all aliases and the only real named type involved (Response) is a metadata-only type, the resulting type will always come out anonymous. Not sure how easy it will be to fix this.

timotheeguerin commented 1 year ago

I feel like for the docs we should be able to trace back if a type was declared in an alias and expose that to the user.

markcowl commented 1 year ago

@markcowl find issue on template docs

markcowl commented 1 year ago

This is the issue on template documentation that is similar: https://github.com/Azure/typespec-azure-pr/issues/2923

microsoft / typespec

Poor operation template documentation #1972