spki: Document (or improve) how to convert between SubjectPublicKeyInfoOwned and SubjectPublicKeyInfoRef

[str4d]

As part of migrating age-plugin-yubikey to yubikey 0.8 (using VS Code and rust-analyzer), I encountered SubjectPublicKeyInfoOwned and SubjectPublicKeyInfoRef. None of the documentation visible to rust-analyzer gave any explanation of how to convert between the two, and because OwnedToRef is a custom trait in the der crate (instead of having any relationship to the standard AsRef or Borrow traits), everything I attempted to do failed. I only discovered the correct mechanism as a side-effect of trawling through the x509-cert crate's code.

The conversion process should be greatly simplified, by way of one or more of the following:

• Document OwnedToRef usage (as well as other similar traits) within the spki crate, in the places that users will see via rust-analyzer:
  • The SubjectPublicKeyInfoOwned and SubjectPublicKeyInfoRef struct documentation.
  • Maybe also in the top-level crate docs (or at least have links there pointing people to the full documentation for how non-optional traits from other crates are used).
• Replace or augment OwnedToRef with either AsRef or Borrow as appropriate, or clearly document on OwnedToRef why it exists separately from those two standard traits.

[tarcieri]

Note that RefToOwned and OwnedToRef don’t have the same shape as traits like AsRef and Borrow.

Perhaps they could be named better (open to suggestions) but their goal is to convert between types which fully own their contents versus one with a lifetime and fields containing borrowed contents, where the latter are needed to support heapless no_std targets.

However note that they operate on and return owned structs and not references to them, as AsRef/Borrow would require. Making them work (if it’s even possible) would require unsafe.

[str4d]

That explanation makes sense to me, and indeed seems like excellent information to include in the documentation of RefToOwned and OwnedToRef 🙂

[tarcieri]

Fixed in #1498