stabilized compiler_fences (fixes #41091)

[budziq]

I did not know what to proceed with "unstable-book" entry. The feature would no longer be unstable so I have deleted it. If it was the wrong call I'll revert it (unfortunately his case is not described in the CONTRIBUTING.md).

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @sfackler (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.

[alexcrichton]

Thanks! Maybe the docs could move to the function?

[budziq]

Maybe the docs could move to the function?

I've translated part of the unstable-book article into an example. I'm not sure if it didn't came out forced.

[alexcrichton]

@bors: r+

Sure!

cc @jonhoo

[bors]

📌 Commit 571941b has been approved by alexcrichton

[jonhoo]

Hmm, I think I would argue for more of the text from the unstable book to be incorporated into the documentation for compiler_fence. This is a very specialized function, and having the docs to explain that is probably a good idea. In particular, I think the last paragraph before the Examples header, and the first paragraph after, could be kept verbatim in the docs for compiler_fence, perhaps under a heading of "Usage"? There's also the question about whether it is appropriate to refer readers to the equivalent function in C++ like the unstable book text does, though I feel less strongly about that.

[alexcrichton]

@bors: r-

@budziq want to update with @jonhoo's thoughts?

[budziq]

want to update with @jonhoo's thoughts?

@alexcrichton Gladly! Although I might not have time to approach it this weekend.

In particular, I think the last paragraph before the Examples header, and the first paragraph after, could be kept verbatim

@jonhoo I've originally omitted these paragraphs as these convey the same message as current docs present above compiler_fence (although in much terser form). I can replace one with the other.

There's also the question about whether it is appropriate to refer readers to the equivalent function in C++

I'm not sure about linking to C++ reference but I would prefer not to point to StackOverflow, leaving only the linux kernel link.

[budziq]

I've updated the docs with the best I could come up with :)

[alexcrichton]

@bors: r+

[bors]

📌 Commit 5f62c0c has been approved by alexcrichton

[jonhoo]

LGTM 👍

[nalply]

Perhaps a typo? IS_READY instead of IS_READ (perhaps occurs several times)

[jonhoo]

Yes, this should be IS_READY