Consider representing raw handles with an enum

[Ralith]

As discussed in rust-gamedev/wg#26, this can improve usability by allowing for statically-checked totality and rendering additional traits unnceessary, and does not incur any additional inconvenience for users on platforms which do not support a given windowing system, as inapplicable enum cases can still be conditionally compiled out.

[Osspial]

I can see your point about usability. However, I don't like the idea of exposing an exhaustive enum, since that makes it impossible to add support for new backends on multi-platform systems (Linux is the main one I'm aware of, but there may be others).

I've gone ahead and made an enum-based variant here, with rendered docs. Feedback? I'm using unstable features to add additional documentation annotations, but it still builds fine on stable so that shouldn't be too much of a concern.

[Osspial]

cc #1 @kvark

[Ralith]

Using a non-exhaustive enum and adding support for new backends risks breaking working applications by causing them to appear to support the new backends at compiletime while at runtime they have no option but to messily bail out. On the flipside, having to make beaking updates of an interop crate whose entire purpose is to preclude breaking updates isn't ideal either...

[Osspial]

Using a non-exhaustive enum and adding support for new backends risks breaking working applications by causing them to appear to support the new backends at compiletime while at runtime they have no option but to messily bail out.

Even if we were using an exhaustive enum, wouldn't applications still have to messily bail out when running in an environment they didn't expect? Using an exhaustive enum wouldn't stop people from trying to run an application designed for X11/Wayland under the Linux Framebuffer.

[Ralith]

I'm specifically concerned about when there are multiple valid windowing systems available at runtime. For example, (most?) Wayland environments are more or less backwards-compatible with X11, but Wayland should be preferred when both are available. If this library were written to only support X11 on linux, and then later extended with Wayland support, then applications which were written prior to that update would cease working on Wayland after updating the library, because the library would preferentially select a case that is not handled. That behavior is probably not expected from a minor version update.

One solution would be for the library to always select the oldest option when multiple are available, but that leads to permanently low-quality support for new windowing systems. Another solution would be to use an exhaustive enum and then necessarily bump the major version of the library whenever a new windowing system is added for an existing platform. Compatibility between major versions could be preserved by using the semver trick, with old version facades setting a flag to explicitly disable new windowing system support. As we've seen with rand, though, this isn't trivial to get right and can be very disruptive to the ecosystem if something goes wrong. The additional maintenance load isn't great either.

Having written that all out, I'm coming around to just using a non-exhaustive enum. The breakage is an unpleasant surprise, but new windowing systems that can coexist with their predecessors are not frequently introduced, breakage will not effect pre-existing binaries, and the fix should usually be trivial.

[Osspial]

Closing since #6 was merged.