Document the struct and a few methods

compiler/rustc_index/src/vec.rs

@@ -12,10 +12,26 @@ use std::vec;
 use crate::{Idx, IndexSlice};
 
 /// An owned contiguous collection of `T`s, indexed by `I` rather than by `usize`.
+/// Its purpose is to avoid mixing indexes.
 ///
 /// While it's possible to use `u32` or `usize` directly for `I`,
 /// you almost certainly want to use a [`newtype_index!`]-generated type instead.
 ///
+/// This allows to index the IndexVec with the new index type:
+///
+/// ```
+/// use crate as rustc_index;
+/// use rustc_index::{IndexVec, newtype_index};
+///
+/// newtype_index! {
+///   pub struct MyIdx {}
+/// }
+///
+/// let my_index_vec: IndexVec<MyIdx, u32> = IndexVec::from_raw(vec![0,1,2,3]);
+/// let idx: MyIdx = MyIdx::from_u32(2);
+/// assert_eq!(my_index_vec[idx], 2);
+/// ```
+///
 /// [`newtype_index!`]: ../macro.newtype_index.html
 #[derive(Clone, PartialEq, Eq, Hash)]
 #[repr(transparent)]
@@ -25,11 +41,13 @@ pub struct IndexVec<I: Idx, T> {
 }
 
 impl<I: Idx, T> IndexVec<I, T> {
+    /// Constructs a new, empty `IndexVec<I, T>`.
     #[inline]
     pub const fn new() -> Self {
         IndexVec::from_raw(Vec::new())
     }
 
+    /// Constructs a new `IndexVec<I, T>` from a `Vec<T>`
     #[inline]
     pub const fn from_raw(raw: Vec<T>) -> Self {
         IndexVec { raw, _marker: PhantomData }
@@ -59,6 +77,7 @@ impl<I: Idx, T> IndexVec<I, T> {
         IndexVec::from_raw(vec![elem; universe.len()])
     }
 
+    /// Creates a new `IndexVec` with n copies of `elem`
     #[inline]
     pub fn from_elem_n(elem: T, n: usize) -> Self
     where