Document target_feature and cfg_target_feature.

[ehuss]

• Stabilization PR: Stabilize x86/x86_64 SIMD rust#49664
• RFC 2045 target_feature and cfg_target_feature
  • Tracking issue: Tracking issue for RFC 2045: improving #[target_feature] rust#44839
  • Tracking issue cfg_target_feature: Tracking issue for cfg_target_feature rust#29717
• RFC 2325 Stable SIMD
  • Tracking issue: Tracking issue for stable SIMD in Rust rust#48556

Closes #286

[Havvy]

Other than the nits, the documentation looks good. Nice work.

But, and this is a big but, I think that platform features should be discussed outside of the target_feature attribute as its own section and then the attribute can point to that. But if you don't want to rewrite the entire PR, we can just open that as an issue and merge this as is.

[ehuss]

I think that platform features should be discussed outside

I wouldn't mind rearranging things, though I don't quite see what it would look like. I am concerned that the tables will get quite large as more features are stabilized. I'm not sure what else can be said about platform features, though.

[ehuss]

Oh, I was also wondering about pinging some of the people for review who know this stuff well (like alex or gnzlbg). The "Implicitly Enables" was particularly difficult to figure out. I think it is correct, but they should know more.

[Centril]

Textually, this is great; cc @gnzlbg for contents.

Done

[gnzlbg]

Is the table below only intended to document the stable target features?

I know it wouldn't be great to link to the compiler implementation as the source of documentation, and I'll try to keep this in sync as new PRs are merged, but particularly for those who want to learn about the unstable features, the compiler source might be useful (e.g. here: https://github.com/rust-lang/rust/blob/master/src/librustc_codegen_llvm/llvm_util.rs#L96).

[Havvy]

Everything in the reference documents what is stable (as of the current nightly; the reference updates on the website alongside rustc releases)

For unstable things, there's the unstable book (https://github.com/rust-lang/rust/tree/master/src/doc/unstable-book).

[gnzlbg]

I don't know whether unsafe superpowers are documented in the reference, but being able to call a target-feature function without proving that the platform the code is running on supports the feature is an unsafe super power.

EDIT: it might be worth it to add this super-power to the list, and link from them to here.

[gnzlbg]

So forget about this, the the unsafe super-powers are documented here: https://doc.rust-lang.org/reference/unsafety.html#unsafety but they already contain "calling unsafe functions" which is what applies for these.

We'll only need to update this list if the target-feature 1.1 RFC gets merged.

[gnzlbg]

LGTM. I leave it up to you whether you want to link to the compiler source or not.

Thank you for doing this.

[Havvy]

💟 Thanks!