Request for porters, think about the end user a little more :C

This is a little bit of a rant based on at least 5 projects I have tried to use lately non of which do what I am about to describe.
When porting a library from C/C++ to rust or when adding bindings, there are only 2 good ways to go about it.

The first option, what I think is the best, is you create a 1:1 mapping from the C version to the rust version. So each struct has a matching struct, each function a matching function. This means the user can relay in the existing docs and code to figure out how to use the rust bindings, it also makes it easier to port code into rust.

The second option, maybe the C/C++ is too unsafe or maybe for some reason it;s just too hard to do a 1:1 port. In this case have at least 3 examples on achieving common goals using your tool up to date in the first page of the docs. Documenting everything might take too long, I get that, so at least have a few use cases.

I will give an example of the frustration with the spirv_cross crate.

In C++ spirv_cross has a parsing structure you can use like this:

spirv_cross::CompilerGLSL glsl(spirv_source);

Naturally as a user I expect the rust bindings to have the same struct. but searching the keyword on the docs yields no such struct. A manual search confirms that no such struct exits.

Looking at the docs there is no snippet showing how to use spirv_cross on rust, and it's not self evident from the available structs.

Putting all the time into making the tool work but not helping the end user learn how to use it is wasted effort at the end of the day.

And it's not just shaderc, as mentioned there's at least another 4 crates that also port bindings from C but they completely change the API without documenting anything, leaving the user in the dark as to how to actually achieve anything with the crate.

Please, think about the end user when putting work into the port, creating a public crate without helping people use it means you put a lot of work for nothing or almost nothing.