Functions should say in their docs what intrinsics / assembly they implement

[Lokathor]

Right now you need the source files open to get intrinsic names, and then you'd also need to go to the intel intrinsics guide to see what the actual assembly instruction of the intrinsic is.

We can do better.

Proposed format:

/// short description.
///
/// extra details, if any
/// ```
/// doc test example
/// ```
/// * **Intrinsic:** [`name`]
/// * **Assembly:** `op arg, arg, arg`

Remember that the first line of the docs shows up in the function's summary when listing the functions of an entire module, so we want that to be short and sweet, and then everything past that first line can be various levels of info dump about what's going on.

Contribution Guidelines: If you want to try your hand at this, pick a small module with 10 or less functions (such as adx or bmi1) and do it for just that one small module. Then we can see if it's a comfortable format to look at and so on.

[Lokathor]

I've marked this as "good first issue". I don't think that a contributor would solve this all in a single PR, but doing this for a module at a time would be an appropriate PR.

[Lokathor]

Small update: if we put the intrinsic function name in square brackets with backticks (updated in the above) then we'll get intra-doc links to the core::arch function. Might as well.

[Lokathor]

Oof, we got a mild problem @joshtriplett, rustdoc search doesn't search the body of docs, only names, params, and return types.

So if you say in a function's docs

/// * **Intrinsic:** [`_mm256_broadcastsi128_si256`]
/// * **Assembly:** `vbroadcasti128 ymm, m128`

A search for "vbroadcasti128" and "_mm256_broadcastsi128_si256" would both turn up nothing at all.

[joshtriplett]

On Fri, May 15, 2020 at 02:45:34PM -0700, Lokathor wrote:

Oof, we got a mild problem @joshtriplett, rustdoc search doesn't search the body of docs, only names, params, and return types.

So if you say in a function's docs

/// * **Intrinsic:** [`_mm256_broadcastsi128_si256`]
/// * **Assembly:** `vbroadcasti128 ymm, m128`

A search for "vbroadcasti128" and "_mm256_broadcastsi128_si256" would both turn up nothing at all.

That's unfortunate (and I hope we can at some point add a "full documentation" tab to the rustdoc search), but I think there's still a great deal of value in adding this, to help people cross-reference and understand.

[Lokathor]

Yeah I'll continue to slowly add the info as I go and hope for rustdoc search functionality to catch up some day.

[HadrienG2]

I just found out about this rustdoc feature which might come in handy here: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#alias