Generate a documentation page for core::mem::transmute.

[jrvanwhy]

In #[no_std] environments, std::mem::transmute is unavailable. Searching for "core transmute" online only pulls up core::intrinsics::transmute, which is behind the (unstable) core_intrinsics feature flag. Users wishing to use transmute in #[no_std] environments typically should use core::mem::transmute instead, as it is stable. This documentation makes core::mem::transmute discoverable.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @shepmaster (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[tesuji]

I'm not a contributor. My thought is that when you search transmute in Rust doc, you would see all posible output.

[shepmaster]

when you search transmute in Rust doc,

And (unfortunately in this case), the intrinsics:: one appears before the one we'd want people to use (mem::).

I think this is fine, but I'd wonder how it would look for std::intrinsics::transmute — does it suggest using core::mem?

[shepmaster]

Now, does this new fancy thing work yet...

r? @rust-lang/docs

[shepmaster]

No, it does not.

r? @QuietMisdreavus

[jrvanwhy]

when you search transmute in Rust doc,

And (unfortunately in this case), the intrinsics:: one appears before the one we'd want people to use (mem::).

Actually, the one we want (core::mem::transmute) does not appear in the list at all. core::mem::transmute_copy does appear, as does std::mem::transmute. I suspect there's some mechanism trying to shepherd users towards std rather than core for items that exist in both, but that can be troublesome for #![no_std] users.

I think this is fine, but I'd wonder how it would look for std::intrinsics::transmute — does it suggest using core::mem?

Unfortunately, the recommendation does show up in std::intrinsics::transmute's docs. It also appears in std::mem::transmute's docs. I'm not sure if it's possible to disable that -- if we can't prevent it, then this needs to be reworded.

[shepmaster]

Hm. It's because core::mem::transmute is just a re-export:

rust/src/libcore/mem.rs

Lines 17 to 18 in 19f8958

	#[stable(feature = "rust1", since = "1.0.0")]
	pub use intrinsics::transmute;

[GuillaumeGomez]

You can (will be able to) filter your search (currently not in stable, only in nightly and beta...) so you won't have the search issue anymore. However, I approve the precision add!

[scottmcm]

These docs are going to show up for all four of {core|std}::{mem|intrinsics}::transmute, right? It might be worth pointing at both mem locations, in that case.

[QuietMisdreavus]

A better solution than adding the extra blurb in the docs is to apply #[doc(inline)] to the pub use intrinsics::transmute statement instead. This will make a new page for core::mem::transmute appear, which will also add it to the search index.

[scottmcm]

Ooh, nice, @QuietMisdreavus! That sounds great, and would let us make the docs for the intrinsic just be "don't use this; use it from core instead". Oops, I misunderstood.

[QuietMisdreavus]

and would let us make the docs for the intrinsic just be "don't use this; use it from core instead"

Actually, the doc for the intrinsic is going to be the same in all four places it's available, because it's just re-exported around. There's no way to fix that, since rustdoc doesn't let you add different docs to a re-export.

[jrvanwhy]

A better solution than adding the extra blurb in the docs is to apply #[doc(inline)] to the pub use intrinsics::transmute statement instead. This will make a new page for core::mem::transmute appear, which will also add it to the search index.

Thank you! I'll give that a try -- it sounds like a much better solution.

[jrvanwhy]

I added the doc page for core::mem::transmute. For my own use cases, this change would've been plenty, so I removed the additional paragraph from the doc comment. I can replace the comment if others feel that transmute is sufficiently unique to deserve a "recommended exports of" comment.

[QuietMisdreavus]

Sorry for letting this sit for so long! Let's get this merged!

@bors r+ rollup

[bors]

📌 Commit 1c8c94a has been approved by QuietMisdreavus