Hello. I'm starting out learning some gfx-hal using the Learning gfx-hal series by False Idol Factory.
I've noticed some usages of unsafe, which is fair for such a library. However I was wondering if there exists some documentation on which guarantees the programmer must uphold in order to avoid memory errors/UB. I imagine that creating a comprehensive list of guarantees needed for the whole API may be a practically insurmountable task - multiplied even due to multiple backends which would need to be checked. However I found that any such specification is mostly missing.
I have found the issue #2453 (Mark most functions as unsafe) with some discussion about unsafety, though that just revolved around the decision of adding the unsafe keyword in various places in the public API. There is the bullet point "Function docs include error, panic, and safety considerations ([C-FAILURE])" in #1254 ([meta] follow Rust API guidelines), amongst a plethora of other suggestions, (presumably) yet unchecked.

With that said, I want to ask what are roughly the current or future plans about unsafe in the public API and safety-documentation? And how do programmers deal with the unsafety in the current API - is it basically just hoping for the best?

I don't mean to come across as being too critical. Safety is a big topic for Rust and I imagine some may have a hard stance on issue, but me, I am merely curious. I can't really judge the development of this project, for I have not followed it well, but I believe your efforts are genuine and well. Thanks for your work :)

kvark: I see. I've actually been reading the code for the OpenGL and Vulkan backends do. I know some OpenGL and a few Vulkanic concepts, but it seems like a workable approach for now.
I'll be happy to update the documentation with what I've found with a PR when I've finished the tutorial.

Btw, what's the difference between "Valid Usage" and "Valid Usage (Implicit)"?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       there's also the problem that both gl and dx11 will have parts of the api that won't work correctly because of the difference in abstraction

Btw, what's the difference between "Valid Usage" and "Valid Usage (Implicit)"?

not exactly sure, I assume "implicit" is about rules inherited from some other scope where they are described, and just duplicated in the places they apply to

Ah, it's specified in the spec:

3.7.2. Implicit Valid Usage
Some valid usage conditions apply to all commands and structures in the API, unless explicitly denoted otherwise for a specific command or structure. These conditions are considered implicit, and are described in a block labelled “Valid Usage (Implicit)” following each command or structure they apply to.

Thanks for the quick answer :)