Merge pull request rust-bitcoin#24 from tcharding/12-30-docs

Improve rustdocs

Author: tcharding

examples/point.rs

@@ -17,7 +17,9 @@ fn main() {
 
     println!();
     println!("Looking in map for key: {}", a);
-    let found = map.get(Ordered::from_ref(&a)).expect("failed to look up key");
+
+    let found = map.get(Ordered::from_ref(&a)).expect("handle item not found");
+
     println!("Found it, with value: {}", found);
 }
 

src/lib.rs

@@ -1,7 +1,12 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! Provides a wrapper for types that can technically implement `PartialOrd`/`Ord`
-//! but for semantic reasons it is nonsensical.
+//! Provides a wrapper for types that can technically implement `PartialOrd`/`Ord` but for semantic
+//! reasons it is nonsensical.
+//!
+//! `PartialOrd` and `Ord` are often useful and/or required. For example, [`Ordered`] allows one to
+//! use such a type as a key in a `BTreeMap` (which requires ordered keys).
+//!
+//! For a full example see `examples/point.rs`.
 //!
 //! # Examples
 //!
@@ -26,12 +31,6 @@
 //!     }
 //! }
 //!
-//! impl fmt::Display for Point {
-//!     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-//!         write!(f, "({}, {})", self.x, self.y)
-//!     }
-//! }
-//!
 //! /// `Ordered` allows users to derive `PartialOrd` on types that include a `Point`.
 //! #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 //! struct Adt {
@@ -87,17 +86,11 @@ pub trait ArbitraryOrd: Eq + PartialEq {
 ///     }
 /// }
 ///
-/// impl fmt::Display for Point {
-///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-///         write!(f, "({}, {})", self.x, self.y)
-///     }
-/// }
-///
 /// let point = Point { x: 0, y: 1 };
 /// let ordered = Ordered(point);
 ///
-/// assert_eq!(*ordered, ordered.into_inner()); // Explicitly deref or use `into_inner()`.
-/// assert_eq!(&ordered.0, ordered.as_ref()); // Use `AsRef` or `as_ref()`.
+/// assert_eq!(*ordered, point); // Use `ops::Deref`.
+/// assert_eq!(&ordered.0, ordered.as_ref()); // Use the public inner field or `AsRef`.
 /// ```
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 #[repr(transparent)]