Improve the first example in the documentation

Fix #82

Author: TeXitoi

CHANGELOG.md

@@ -1,3 +1,7 @@
+# v0.2.5 (2018-XX-XX)
+
+* Improve first example in the documentation ([#82](https://github.com/TeXitoi/structopt/issues/82)) by [@TeXitoi](https://github.com/TeXitoi)
+
 # v0.2.5 (2018-03-07)
 
 * Work around breakage when `proc-macro2`'s nightly feature is enabled. ([#77](https://github.com/Texitoi/structopt/pull/77) and [proc-macro2#67](https://github.com/alexcrichton/proc-macro2/issues/67)) by [@fitzgen](https://github.com/fitzgen)

src/lib.rs

@@ -25,22 +25,34 @@
 //!
 //! First, let's look at an example:
 //!
-//! ```
-//! #[macro_use] extern crate structopt;
+//! ```should_panic
+//! #[macro_use]
+//! extern crate structopt;
+//!
 //! use std::path::PathBuf;
-//! #[derive(StructOpt)]
+//! use structopt::StructOpt;
+//!
+//! #[derive(Debug, StructOpt)]
 //! #[structopt(name = "example", about = "An example of StructOpt usage.")]
 //! struct Opt {
-//!     #[structopt(short = "d", long = "debug", help = "Activate debug mode")]
+//!     /// Activate debug mode
+//!     #[structopt(short = "d", long = "debug")]
 //!     debug: bool,
-//!     #[structopt(short = "s", long = "speed", help = "Set speed", default_value = "42")]
+//!     /// Set speed
+//!     #[structopt(short = "s", long = "speed", default_value = "42")]
 //!     speed: f64,
-//!     #[structopt(help = "Input file", parse(from_os_str))]
+//!     /// Input file
+//!     #[structopt(parse(from_os_str))]
 //!     input: PathBuf,
-//!     #[structopt(help = "Output file, stdout if not present", parse(from_os_str))]
+//!     /// Output file, stdout if not present
+//!     #[structopt(parse(from_os_str))]
 //!     output: Option<PathBuf>,
 //! }
-//! # fn main() {}
+//!
+//! fn main() {
+//!     let opt = Opt::from_args();
+//!     println!("{:?}", opt);
+//! }
 //! ```
 //!
 //! So `derive(StructOpt)` tells Rust to generate a command line parser,