Clarify WTF-8 docs and private os_str::Slice type name

[teor2345]

This PR is a follow-up to PR #140159, which clarifies two things:

• the WTF-8 safety comment was confusing, either surrogate condition is actually sufficient for safety, both are not required
• the private os_str::Slice type name is easily confused with std::slice

Happy to bikeshed the OsSlice name, other alternatives are OsStrSlice and StrSlice. Now it's got a distinct name from std::slice, it's easy to search and replace.

cc @thaliaarchi @workingjubilee

[rustbot]

r? @ibraheemdev

rustbot has assigned @ibraheemdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[thaliaarchi]

The comment change looks good. Can you rewrap it to 80 columns, though? There's no reason not to, since you're already touching the whole paragraph.

---

I'm not convinced that the Slice name needs to change. It's an implementation detail and it being within an os_str module with all the logic dealing with OsStr is sufficient to avoid confusion, in my opinion. However, if we do rename it, Buf should be renamed analogously; otherwise the situation becomes worse, as this would make these closely related types become logically disconnected.

That being said, here are some alternatives that I think would be better than OsSlice/Buf:

• OsStrImpl/OsStringImpl
• OsStrRepr/OsStringRepr
• OsStrInner/OsStringInner
• OsStr/OsString, referenced with os_impl::OsStr/os_impl::OsSlice
• OsStr/OsString, referenced with repr::OsStr/repr::OsSlice
• OsStr/OsString, referenced with inner::OsStr/inner::OsSlice

The last three would import the module like use crate::sys::os_str as alias; and use the types with that qualifier.

Semantically, I prefer “impl” the most, because these are platform adaptors implementing a common interface. “Inner” works, as they're indeed the inner types of OsStr/OsString, but they, in turn, have [u8]/Vec<u8> or Wtf8/Wtf8Buf then [u8]/Vec<u8> as their inner types, so what layer deserves to be called the “inner” type? As for “repr”, I'd consider the [u8]/Vec<u8> layer to be where the data is represented, so I don't think it fits.

One thing I like about these names over Slice/Buf is that they're closer to the public names. I've wanted to rename Wtf8/Wtf8Buf to Wtf8Str/Wtf8String for that reason.

I think it's worth fleshing out name ideas more, but I'm currently leaning towards keeping the current names.