Design choice for enumerations

[timsneath]

If I may offer a little editorial from the peanut gallery, I'm not a huge fan of this grand redefinition of ints as enums. It might be idiomatic for C#, but it doesn't feel spiritually aligned with the C API it's wrapping. I'm unwinding it in my Dart projection, but it means extra work for me to try and return back to the API that you're scraping from. I'm guessing that less strongly-typed languages might well dislike this even more.

Is there a different approach? Perhaps keeping these as ints but using an attribute for the parameter and the constants to provide a categorization hint without changing the actual type signature of these APIs? #346 is a good example of what I'm talking about here.

Thanks for listening!

/cc @sotteson1 @kennykerr

[sotteson1]

It's a design goal of the project to replace int/uint with enums as much as possible. This helps developers discover which values are allowed for parameters. If these APIs were being written today they would use enums instead of just int/uint.

I looked at #346 and that is a bug in the docs scraper. It should not have gotten rid of the pointer.

[mikebattista]

@timsneath, bugs aside, could you provide more details on the unwinding that you're doing? Are you just treating all enums as ints?

[timsneath]

Yeah, these used to be a straight projection for me. This weekend I had to write a bunch of extra code (=> more surface area, => more risk of bugs) to special case for this, along the following lines:

    if (typeIdentifier.typeArgs.first.type?.parent?.typeName == 'System.Enum') {
      return 'Pointer<Uint32>';
    }

I'm definitely not covering all the cases here. For example, these could be a Uint32 or a Pointer<Uint32> (for an out parameter. Perhaps they might even be a Pointer<Pointer<Uint32>>, if the API returns an array of these values. And yes, for now I'm assuming that they all map to a Uint32 type. Perhaps I should really be interrogating the enum to figure out what it represents.

This doesn't feel like it maps to the principle of "striving for more of an originalist approach while preserving/adding optional metadata to enable, but not force, activism" (since it's not optional metadata: I have to deal with it). I'd be happier if these were attributes that could be ignored or interpreted depending on the needs of a projection author. But I'm just one of many potential customers, obviously.

[weltkante]

just for the record, there occasionally are flags that are not 32 bit so fixed fallback to uint32 is definitely wrong

like said elsewhere in the discussion you should be using the underlying type of the enum, everything should already be in the medata, just unwrap enums to their underlying type whenever you encounter them and you should be fine

[timsneath]

It's doable -- it's just extra work to try and get back to the state where I started. Hence the comment.

It's obviously your product, and your design decisions to make. But if you don't mind me offering my unsolicited feedback -- what I'm trying to build is a faithful representation of the Win32 API that has several decades of samples, documentation, and muscle memory. Fidelity is my primary concern.

I'm rather worried that this isn't the principle that you're building on, and that the metadata is going to keep evolving (as it has done over the last month or two) based on a desire to somehow reinvent or modernize the API. You have that already -- it's UWP / WinUI. My own vote, for as little as it's worth, is that you supplement the API with additional hints, rather than redefine it.

[weltkante]

just to be clear, I'm not part of the team, just commented here because it looked like an oversight was (potentially) being made by replacing with 32 bit integers even if the underlying type is different; if anything this is now more clear for other potential readers

[timsneath]

Got it -- thanks for the clarification, @weltkante!

[mikebattista]

@kennykerr / @AArnott what are your thoughts here?

[AArnott]

We got a lot of feedback from users who expected enums. And we actually want to raise the level from the decades-old C style headers a little bit, without sacrificing the usefulness of the docs and existing code that was written back then.
So if a particular language doesn't like the projections much, I think the projection can remove it. It is easier to remove richness within the projection from the metadata than to synthesize it.

[kennykerr]

I thinks its a reasonable compromise. You can easily check the underlying type of the enum (or the field constant types) and then unroll them. Steve's still commited to preserving the original names of the constants so that should be straightforward.

The alternative is making them all constants and then adding an attribute to each constant to tell consumers how to group them. While that is a reasonable approach, it would probably result in a much larger winmd due to all the extras attribute blobs and I'm already rather concerned about how big the metadata is.

[weltkante]

I want to emphasize the importance of using the underlying type, since there are enumified #defines that are not 32 bit integers.