slice docs could use example functions, clear header

[workingjubilee]

The API docs for the slice type describes what [T] is and explains the meaning of &[T] and &mut [T], but this can still be vague for Rust programmers. A programmer with even a modest interest in using Rust for what it's been strongly advertised for, systems programming, is very likely to encounter the need to slice bytes between days 0 to 7, when they have not yet adjusted to Rust syntax and are not clear on why the type's identification in a function signature or type annotation is not the same as its name. In addition, it is easy to miss the type annotations in the existing examples.

Recently, on nightly, the struct declaration of e.g. std::vec::Vec has been made visible, making an easy to read "header" that quickly gives an example of the type. This is very nice for generated structs, especially ones with type parameters, but primitives have a harder time of it, as there's no obvious "declaration" to give to a reader. Instead, the problem to address is an immediate "okay, what does this look like in usage?" So, a clear example of a very simple function signature as one of the visible examples, and possibly raising the descriptions of &[T] and &mut [T] towards the top of the page, may help clarify this.

Reproducer

We tried the documentation page for the slice type.
We expected to see an easy-to-read example of a function that accepts or returns slices.
Instead, we scanned the page without finding a clear example of such, and found it easy to miss the existing examples.
May require being mildly tired or undercaffeinated to reproduce.

Docs Version

# at the time of this issue, this could use improvement for both the stable and nightly std API docs
rustc 1.54.0-nightly (9111b8ae9 2021-05-26)
rustc 1.52.1 (9bc8c42bb 2021-05-09)

[inquisitivecrystal]

@rustbot label +A-slice -C-bug +C-enhancement +T-doc +T-libs

[Kimundi]

Piggy backing off of this:

• The slice docs are currently also unclear about whether [T] contains pointer+length or not:

  Slices are a view into a block of memory represented as a pointer and a length.

• They also imply that you can only have them behind a reference:

  Slices are either mutable or shared.

• While also using the type differently on the next lines:

  assert_eq!(2 * pointer_size, std::mem::size_of::<Box<[u8]>>());

We should probably clearly separate the "concept" of a slice with pointer+len from the type [T] that is pointed at, which is also called a slice.

Also it seems to me as if the slice type docs and the slice module docs started to drift away from each other:

• https://doc.rust-lang.org/std/primitive.slice.html
• https://doc.rust-lang.org/std/slice/index.html