Add more links in documentation

Following rust-lang/rust#89010, add links to referenced items in the
parts of this crate's documentation that unique here and not found in
`std`.

Author: clint-white

README.md

@@ -2,7 +2,8 @@
 
 ![Rust](https://github.com/sekineh/binary-heap-plus-rs/workflows/Rust/badge.svg)
 
-Enhancement over Rust's `std::collections::BinaryHeap`.
+Enhancement over Rust's
+[`std::collections::BinaryHeap`](https://doc.rust-lang.org/stable/std/collections/struct.BinaryHeap.html).
 
 It supports the following heaps and still maintains backward compatibility.
 - Max heap
@@ -25,8 +26,8 @@ This crate requires Rust 1.36.0 or later.
 
 # Changes
 
-See CHANGELOG.md.
-https://github.com/sekineh/binary-heap-plus-rs/blob/master/CHANGELOG.md
+See
+[CHANGELOG.md](https://github.com/sekineh/binary-heap-plus-rs/blob/master/CHANGELOG.md).
 
 # Thanks
 

src/binary_heap.rs

@@ -432,31 +432,37 @@ impl<T: fmt::Debug, C: Compare<T>> fmt::Debug for BinaryHeap<T, C> {
 }
 
 impl<T, C: Compare<T> + Default> BinaryHeap<T, C> {
-    /// Generic constructor for `BinaryHeap` from `Vec`.
+    /// Generic constructor for `BinaryHeap` from [`Vec`].
     ///
     /// Because `BinaryHeap` stores the elements in its internal `Vec`,
     /// it's natural to construct it from `Vec`.
+    ///
+    /// [`Vec`]: https://doc.rust-lang.org/stable/std/vec/struct.Vec.html
     pub fn from_vec(vec: Vec<T>) -> Self {
         BinaryHeap::from_vec_cmp(vec, C::default())
     }
 }
 
 impl<T, C: Compare<T>> BinaryHeap<T, C> {
-    /// Generic constructor for `BinaryHeap` from `Vec` and comparator.
+    /// Generic constructor for `BinaryHeap` from [`Vec`] and comparator.
     ///
     /// Because `BinaryHeap` stores the elements in its internal `Vec`,
     /// it's natural to construct it from `Vec`.
+    ///
+    /// [`Vec`]: https://doc.rust-lang.org/stable/std/vec/struct.Vec.html
     pub fn from_vec_cmp(vec: Vec<T>, cmp: C) -> Self {
         unsafe { BinaryHeap::from_vec_cmp_raw(vec, cmp, true) }
     }
 
-    /// Generic constructor for `BinaryHeap` from `Vec` and comparator.
+    /// Generic constructor for `BinaryHeap` from [`Vec`] and comparator.
     ///
     /// Because `BinaryHeap` stores the elements in its internal `Vec`,
     /// it's natural to construct it from `Vec`.
     ///
     /// # Safety
     /// User is responsible for providing valid `rebuild` value.
+    ///
+    /// [`Vec`]: https://doc.rust-lang.org/stable/std/vec/struct.Vec.html
     pub unsafe fn from_vec_cmp_raw(vec: Vec<T>, cmp: C, rebuild: bool) -> Self {
         let mut heap = BinaryHeap { data: vec, cmp };
         if rebuild && !heap.data.is_empty() {

src/lib.rs

@@ -1,62 +1,76 @@
-//! This crate provides `BinaryHeap` which is backward-compatible with `std::collections::BinaryHeap`.
+//! This crate provides [`BinaryHeap`] which is backward-compatible with
+//! [`std::collections::BinaryHeap`].
 //!
 //! Added features include:
 //! * Heaps other than max heap.
-//! * Optional `serde` feature.
+//! * Optional [`serde`] feature.
+//!
+//! [`BinaryHeap`]: struct.BinaryHeap.html
+//! [`std::collections::BinaryHeap`]:
+//! https://doc.rust-lang.org/stable/std/collections/struct.BinaryHeap.html
+//! [`serde`]: https://docs.serde.rs/serde/
 //!
 //! # Quick start
 //!
 //! ## Max/Min Heap
 //!
-//! For max heap, `BiaryHeap::from_vec()` is the most versatile way to create a heap.
+//! For max heap, [`BinaryHeap::from_vec()`] is the most versatile way to create a heap.
 //!
 //! ```rust
-//!     use binary_heap_plus::*;
+//! use binary_heap_plus::*;
 //!
-//!     // max heap
-//!     let mut h: BinaryHeap<i32> = BinaryHeap::from_vec(vec![]);
-//!     // max heap with initial capacity
-//!     let mut h: BinaryHeap<i32> = BinaryHeap::from_vec(Vec::with_capacity(16));
-//!     // max heap from iterator
-//!     let mut h: BinaryHeap<i32> = BinaryHeap::from_vec((0..42).collect());
-//!     assert_eq!(h.pop(), Some(41));
+//! // max heap
+//! let mut h: BinaryHeap<i32> = BinaryHeap::from_vec(vec![]);
+//! // max heap with initial capacity
+//! let mut h: BinaryHeap<i32> = BinaryHeap::from_vec(Vec::with_capacity(16));
+//! // max heap from iterator
+//! let mut h: BinaryHeap<i32> = BinaryHeap::from_vec((0..42).collect());
+//! assert_eq!(h.pop(), Some(41));
 //! ```
 //!
 //! Min heap is similar, but requires type annotation.
 //!
 //! ```rust
-//!     use binary_heap_plus::*;
+//! use binary_heap_plus::*;
 //!
-//!     // min heap
-//!     let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec(vec![]);
-//!     // min heap with initial capacity
-//!     let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec(Vec::with_capacity(16));
-//!     // min heap from iterator
-//!     let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec((0..42).collect());
-//!     assert_eq!(h.pop(), Some(0));
+//! // min heap
+//! let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec(vec![]);
+//! // min heap with initial capacity
+//! let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec(Vec::with_capacity(16));
+//! // min heap from iterator
+//! let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec((0..42).collect());
+//! assert_eq!(h.pop(), Some(0));
 //! ```
 //!
+//! [`BinaryHeap::from_vec()`]: struct.BinaryHeap.html#method.from_vec
+//!
 //! ## Custom Heap
 //!
-//! For custom heap, `BinaryHeap::from_vec_cmp()` works in a similar way to max/min heap. The only difference is that you add the comparator closure with apropriate signature.
+//! For custom heap, [`BinaryHeap::from_vec_cmp()`] works in a similar way to max/min heap. The
+//! only difference is that you add the comparator closure with apropriate signature.
 //!
 //! ```rust
-//!     use binary_heap_plus::*;
+//! use binary_heap_plus::*;
 //!
-//!     // custom heap: ordered by second value (_.1) of the tuples; min first
-//!     let mut h = BinaryHeap::from_vec_cmp(
-//!         vec![(1, 5), (3, 2), (2, 3)],
-//!         |a: &(i32, i32), b: &(i32, i32)| b.1.cmp(&a.1), // comparator closure here
-//!     );
-//!     assert_eq!(h.pop(), Some((3, 2)));
+//! // custom heap: ordered by second value (_.1) of the tuples; min first
+//! let mut h = BinaryHeap::from_vec_cmp(
+//!     vec![(1, 5), (3, 2), (2, 3)],
+//!     |a: &(i32, i32), b: &(i32, i32)| b.1.cmp(&a.1), // comparator closure here
+//! );
+//! assert_eq!(h.pop(), Some((3, 2)));
 //! ```
 //!
+//! [`BinaryHeap::from_vec_cmp()`]: struct.BinaryHeap.html#method.from_vec_cmp
+//!
 //! # Constructers
 //!
 //! ## Generic methods to create different kind of heaps from initial `vec` data.
 //!
-//! * `BinaryHeap::from_vec(vec)`
-//! * `BinaryHeap::from_vec_cmp(vec, cmp)`
+//! * [`BinaryHeap::from_vec`]`(vec)`
+//! * [`BinaryHeap::from_vec_cmp`]`(vec, cmp)`
+//!
+//! [`BinaryHeap::from_vec`]: struct.BinaryHeap.html#method.from_vec
+//! [`BinaryHeap::from_vec_cmp`]: struct.BinaryHeap.html#method.from_vec_cmp
 //!
 //! ```
 //! use binary_heap_plus::*;
@@ -87,11 +101,15 @@
 //!
 //! ## Dedicated methods to create different kind of heaps
 //!
-//! * `BinaryHeap::new()` creates a max heap.
-//! * `BinaryHeap::new_min()` creates a min heap.
-//! * `BinaryHeap::new_by()` creates a heap sorted by the given closure.
-//! * `BinaryHeap::new_by_key()` creates a heap sorted by the key generated by the given closure.
+//! * [`BinaryHeap::new()`] creates a max heap.
+//! * [`BinaryHeap::new_min()`] creates a min heap.
+//! * [`BinaryHeap::new_by()`] creates a heap sorted by the given closure.
+//! * [`BinaryHeap::new_by_key()`] creates a heap sorted by the key generated by the given closure.
 //!
+//! [`BinaryHeap::new()`]: struct.BinaryHeap.html#method.new
+//! [`BinaryHeap::new_min()`]: struct.BinaryHeap.html#method.new_min
+//! [`BinaryHeap::new_by()`]: struct.BinaryHeap.html#method.new_by
+//! [`BinaryHeap::new_by_key()`]: struct.BinaryHeap.html#method.new_by_key
 
 mod binary_heap;
 pub use crate::binary_heap::*;