@Karl The educational notes feature is awesome.
My feeling about presenting to developers is that Unsafe APIs are an unfortunate necessity but not something we need to promote. When we have a new language feature that makes it unnecessary to use Unsafe APIs, that's clearly worth promoting. On the other hand, a helpful how-to for C interop would be worth presenting and would need to cover UnsafePointer APIs. I'm not deeply involved with that right now, but it would be nice to tackle eventually in conjuction with improvements to the compiler, standard library, and possibly other packages.
I started writing docs on type conversion using UnsafePointer APIs last year, ran out of time, and rescheduled the work for later this year. I'd love to make these educational notes as soon as I get back to it.
The rules for related types are a little tricky. They're a working contract for the compiler but aren't officially part of the language. I suspect we could mention the things we know can't be changed with the caveat that it doesn't constitute an official language spec.
In additional to the docs there are several obvious usability bugs that need to be fixed. It's hard to make good recommendations for best practice without fixing them:
- [SR-10246] Support limited implicit pointer conversion when calling C functions.
- [SR-4649] Don't require & to pass value to UnsafeRawPointer
- [SR-10273] Add an UnsafeRaw[Buffer]Pointer API for loading and storing unaligned/packed data
- [SR-11082] Support withMemoryRebound(to:) with mismatched sizes
- Add withUnsafeBufferPointer(to: variable) (no bug yet)
- [SR-11147] Add withUnsafeElements(to: variable) where variable is any homogenous aggregate
- [SR-11156] Add UnsafePointer[KeyPath] API that applies the field's offset
- [SR-11087] Add a closure taking API: UnsafeRaw[Mutable][Buffer]Pointer.withMemoryRebound(to:[capacity:])
- [SR-11300] Provide a RawPointer version of ManagedBuffer
- API for "load from contiguous as: T" (no bug yet)
- Allow comparison of raw and typed pointers (no bug filed)
- Pointers to uninhabited types, OpaquePointer (no bug?)
- rdar://25001764 Detect when a temporary pointer to a writeback buffer is persisted after the function returns (no SR yet)
- rdar://59125380 Custom initializer fails to raise "Inout expression creates a temporary pointer" warning (no SR yet)