Add clause to documentation clarifying the semantics of null values

[Osspial]

Addresses #14 (comment)

[Lokathor]

Approved,

but with the reservation that we should still at some point make the breaking change to use Option<NonNull<c_void>> for fields that are more clearly optional than others. And the method overall should potentially also be changed to be Result<RawWindowHandle, Self::Error>. We should be encoding more of this into the type system whenever we can, even though that's a code break.

[Lokathor]

@bvssvni Hello! I'm pinging you about this docs update as the rep for GLFW, but feel free to send whoever else would be better suited as a contact point. Ossipal is reprisenting winit interests and I'm speaking for how SDL2 works.

Hopefully this makes your GLFW job easier/clearer!

[bvssvni]

@Lokathor I have not followed this discussion, can you fill me in?

[Lokathor]

Essentially, we're confirming that if the backend cannot provide a reasonable value it should return a null pointer or 0 (depending on type) instead of a panic. Then any lib that uses this output is implicitly authorized to try and ask the OS for more info if that happens.

Basically, for GLFW, if there's any case that's expensive or impossible to handle, just throw down a null and the consumer can try on their end if it's absolutely necessary.

For example, SDL2 doesn't give an NSView on Mac, so my wrapper lib just gives the NSWindow and a lib calling for the raw window handle can use that to look up the view themselves if it's really necessary.