From f1d600c6f8cbf7ab23f566e3912f1bebe892b0a6 Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Sat, 25 Jun 2016 16:35:29 -0400
Subject: [PATCH] Expand `std::path::Component` documentation.

Indicate how it gets created and add an example.
---
 src/libstd/path.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/libstd/path.rs b/src/libstd/path.rs
index f413bed86a853..e020945011af2 100644
--- a/src/libstd/path.rs
+++ b/src/libstd/path.rs
@@ -525,6 +525,26 @@ impl<'a> Hash for PrefixComponent<'a> {
 ///
 /// See the module documentation for an in-depth explanation of components and
 /// their role in the API.
+///
+/// This `enum` is created from iterating over the [`path::Components`]
+/// `struct`.
+///
+/// # Examples
+///
+/// ```rust
+/// use std::path::{Component, Path};
+///
+/// let path = Path::new("/tmp/foo/bar.txt");
+/// let components = path.components().collect::<Vec<_>>();
+/// assert_eq!(&components, &[
+///     Component::RootDir,
+///     Component::Normal("tmp".as_ref()),
+///     Component::Normal("foo".as_ref()),
+///     Component::Normal("bar.txt".as_ref()),
+/// ]);
+/// ```
+///
+/// [`path::Components`]: struct.Components.html
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub enum Component<'a> {