Windows-rs: Document naming translation conventions

[Serentty]

Right now, it seems like WinRT-based APIs have their names converted to match Rust naming conventions, whereas Win32 ones do not. This is an unfortunate style mismatch. It would be nice if all APIs could follow the same idiomatic naming conventions.

[Lokathor]

I would say go the other directions: all raw function declarations should use precisely the original name, and leave the snake_case conversion to wrapper crates or whatever higher level thing people care to use.

[kennykerr]

Indeed, this is by design. The WinRT subset is converted in such a way as to appear idiomatic because it is a rich wrapper over the underlying ABI. The remaining Win32, and to some degree COM, APIs preserve their original names because they are largely direct calls to the ABI and typically need wrapping of some kind before they can be used idiomatically in Rust.

[rylev]

It's also idiomatic for bindings for C APIs (which win32 APIs are) retain their original casing. The WinRT APIs exposed by windows-rs are wrappers and meant to be (relatively) idiomatic. They call underlying foreign functions but are Rust APIs themselves and thus deserve Rust idiomatic camel casing. I think we can close this issue.

[Lokathor]

Slow down one moment: What you just said should be put into the readme and at the root level of the crate documents so that people understand what's going on with that.

[rylev]

Sorry! Didn't mean to close prematurely. Happy to put this in the README! ❤️

[rylev]

Names are no longer converted, so closing this.

[Serentty]

@rylev That's interesting. What was the rationale for that? Were misconversions common enough that you decided it wasn't worth the trouble?

[kennykerr]

https://github.com/microsoft/windows-rs/pull/646