Rust: The "unstable" documentation attribute on intrinsics should mention the specific stabilized interface for each individual intrinsic

[bstrie]

Today if one navigates to the docs to, for example, intrinsic::volatile_store (http://doc.rust-lang.org/core/intrinsics/fn.volatile_store.html) you see this warning:

Unstable (core_intrinsics): intrinsics are unlikely to ever be stabilized, instead they should be used through stabilized interfaces in the rest of the standard library

But not all intrinsics have stabilized interfaces, and even when they exist this message is not helpful in determining exactly what those interfaces are.

In the specific example of intrinsic::volatile_store, this should mention that its stabilized interface is ptr::write_volatile (https://doc.rust-lang.org/std/ptr/fn.write_volatile.html).

Intrinsics that do not have such stabilized interfaces should have instead reference issues in the Rust bug tracker that involve creating stabilized interfaces, or alternately a metabug that covers all unstable intrinsics that do not have stable interfaces.

If it has been decided that a given intrinsic will _never_ have a stabilized interface for whatever reason, then the unstable documentation attribute should contain the reason why, and/or a link to the discussion where such a decision was arrived upon.

[bstrie]

Revisiting this, today the intrinsics docs warning message no longer says anything about "instead they should be used through stabilized interfaces in the rest of the standard library", which obviates half of this bug by no longer causing doc readers to wonder at what the stable replacement might be. It also seems that some of the intrinsics have had this issue addressed (e.g. my original example of volatile_store). While it would still be valuable to be sure that any intrinsic with a stable counterpart has that counterpart mentioned in its docs, I'd say that this bug could be closed at the blessing of the docs team.

[QuietMisdreavus]

Triage: Punting this to docs team; the unstable attribute doesn't carry any additional information for intrinsics, so any link back to one's stable interface would have to go into the hand-written portion of their docs. That means that this is effectively a checklist issue, if anyone is interested in taking this up... :eyes:

[DevQps]

@bstrie @QuietMisdreavus I just saw that if you click the "This is a nightly-only experimental API."-part in intrinsic::volatile_store it still expands and shows the message: "intrinsics are unlikely to ever be stabilized, instead they should be used through stabilized interfaces in the rest of the standard library".

I don't mind picking up this issue! I just have three questions:

• Should the expanded intrinsics message be removed (about them unlikely to be ever stabilized)?
• Would you like me to create a checklist? (Create a new issue for this, or somehow copy this in the original message again for easy discoverability when reading this issue?)
• Where could I find the stable interfaces associated with each intrinsic?

[DevQps]

@bstrie @QuietMisdreavus Could you maybe still respond to my previous message? Then hopefully I can take this up soon!

[bstrie]

@DevQps Hello! For definitive answers to those questions I would direct you to ask the docs team, but I can hazard guesses:

1. It's desirable that intrinsics mention that they aren't candidates for stabilization, so that people are absolutely clear about the stability/portability guarantees of the API.

2. A checklist would be great, yes! If you manage to come up with a simple list of intrinsics that need documenting I can edit it into the original issue body.

3. Finding the stabilized versions of each intrinsic is probably a matter of asking around; at least as of when this issue was filed part of the problem was that there wasn't such a document available. :P

[LeSeulArtichaut]

I’ve started working on this, I will probably open a PR pretty soon

For the moment, I have documented the f32/f64 operations, the type_name and type_id functions, and some memory-related functions

[DevQps]

Great to hear that!

[DevQps]

@lcnr @LeSeulArtichaut Thank you both for your hard work! I think #71672 implements this issue and we can probably close this now I guess? Or am I missing something?

@steveklabnik I have been off for a a few months (more then I would have hoped for...) but I am finally back to do some work again :)