[Diagnostics] Add an edu note explaining @_nonEphemeral diags

[owenv]

The goal here is:

• explain how ephemeral pointers can be introduced
• note where they can and cannot be used
• point users in the direction of the withUnsafe* APIs

Suggestions on how to improve the explanations and/or provide better guidance on best practices are welcome, this isn't really my area of expertise. Once SR-12739 is done we should be able to link to that documentation from here as well.

[xwu]

This cries out for an example, or a link to a more elaborate explanation (e.g., the documentation for the APIs mentioned?), or both. I'd wager that there's approximately a 0% chance that someone who is learning about the topic anew from this education note will know what to do based on the dozen words here ("use ... to explicitly manage pointer lifetimes"). We've got a beautiful multi-paragraph explanation of the problem being diagnosed, and then when it comes to any possible solutions, it just...ends.

[owenv]

I think I'll need to come up with some kind of simplified example here, even if it ends up being a bit contrived. The issue with linking to the documentation here is that it's hosted only on developer.apple.com, and there's no way of knowing when and if those links will change. It's the main disadvantage of shipping these notes in the toolchain.

[hamishknight]

Looks fantastic, thank you for writing this up!

[atrick]

Thanks for doing this! I think it's great and agree with all the feedback so far.

When calling functions which cannot safely accept temporary pointer arguments, use the withUnsafe* family of pointer APIs to explicitly manage pointer lifetimes.

Mentioning withUnsafePointer opens up a dangerous door. I think it's the biggest issue with the current warnings. The usual reaction will be to think that merely using withUnsafePointer imbues code with some extra safety--of course it doesn't, it just silences warnings. The educational note is the perfect place to clear this up.

If we leave it as "use withUnsafePointer to manage lifetime" without explaining how to "manage lifetimes", we'll just get a lot of this sort of thing:

struct PointerWrapper {
  var ptr: UnsafePointer<Int>
}

func foo(x: Int) -> PointerWrapper {
  return withUnsafePointer(to: x) {
    PointerWrapper(ptr: $0)
  }
}

It may help just to search through some common Swift packages to see common cases of programmers using withUnsafePointer correctly, and contrast that with incorrect usage.

[owenv]

I ended up adding a more in-depth example of incorrectly initializing an UnsafePointer with UnsafePointer(&x), along with good and bad examples of using withUnsafePointer to fix the problem. After doing a bit of research it looks like this is by far the most common mistake when using ephemeral pointers. Since this note is already kind of long, I'm hesitant to add more examples unless their are concerns this is still insufficient

[hamishknight]

Edits look great!

[xwu]

Agree, this looks great!

[owenv]

@swift-ci please smoke test