Clarify WTF-8 safety docs

[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.

[teor2345]

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.

Done!

I'm not convinced that the Slice name needs to change.

This seems like it could end up being a bikeshed, and it's a different type of change, so I've dropped that commit.