Windows-rs: Consider improving generic param names

[rylev]

Most functions generated are generic over the parameters to facilitate taking multiple types of arguments. In the docs this currently looks like this:

pub unsafe fn SomeFunction<'a, T1__: IntoParam<'a, SomeType>>(some_param: T1__);

While some of this complexity is unavoidable, it might help to give generic params more descriptive name. What strikes the right balance between not being overly verbose and providing proper guidance is tough. The best I can think of is Param1, but that might be too verbose.

[samlh]

You might consider writing the bindings as:

pub unsafe fn SomeFunction<'a>(some_param: impl IntoParam<'a, SomeType>);

...so you don't have to come up with a name for the type parameter at all.

(Using https://doc.rust-lang.org/edition-guide/rust-2018/trait-system/impl-trait-for-returning-complex-types-with-ease.html#argument-position)

I might be missing some reason it's a bad idea, though.

[rylev]

This is certainly a good idea! I believe there is only one downside and that is that users cannot explicitly specify types if there's some kind of ambiguity.

For instance:

// Definition
unsafe fn SomeApi<'a>(arg: impl IntoParam<'a, u32>) { }

// Usage

let num = 1;
SomeApi(num)

This will most likely not compile since num does not have a specific type. Rust defaults to i32 in situations where it cannot infer integer types. With the current strategy of using generic parameters the user could disambiguate with SomeApi::<u32>(num), but this is not possible when the impl syntax is used instead.

[kennykerr]

It is not uncommon to write something like num as u32 when working with Windows APIs. I'll give this a try - I like the simplicity!

[kennykerr]

Thanks for the suggestion. The docs are also a lot more readable now.

pub unsafe fn MessageBoxA<'a>(
    hwnd: impl IntoParam<'a, HWND>, 
    lptext: impl IntoParam<'a, PSTR>, 
    lpcaption: impl IntoParam<'a, PSTR>, 
    utype: MESSAGEBOX_STYLE
) -> MESSAGEBOX_RESULT