diff --git a/src/lib.rs b/src/lib.rs
index ba28fa2c..35573121 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -21,12 +21,35 @@
 //! whether the amount of 'free' arguments in the match is what you expect. Use
 //! `opt_*` accessors to get argument values out of the matches object.
 //!
-//! Single-character options are expected to appear on the command line with a
-//! single preceding dash; multiple-character options are expected to be
-//! proceeded by two dashes. Options that expect an argument accept their
-//! argument following either a space or an equals sign. Single-character
-//! options don't require the space. Everything after double-dash "--"  argument
-//! is considered to be a 'free' argument, even if it starts with dash.
+//! Single-character options use a single dash (e.g. `-u`).
+//! Multiple-character options use two dashes (e.g. `--unified`).
+//!
+//! For multiple-character options:
+//! - required arguments may be provided using either a space or `=`
+//! - optional arguments must be provided using `=`
+//!
+//! Examples:
+//! ```text
+//! --width=80     # required argument via '='
+//! --width 80     # required argument via space
+//! --unified=3    # optional argument via '='
+//! --unified 4    # bad, '4' is treated as a 'free' argument
+//! ```
+//!
+//! For single-character options, arguments may be provided with or without a
+//! space, but not using `=`.
+//!
+//! Examples:
+//! ```text
+//! -u19              # argument without space
+//! -u 19             # argument with space
+//! -u=20             # bad, argument is parsed as '=20'
+//! ```
+//!
+//! The double-dash separator `--` terminates option parsing. Everything after it
+//! is treated as a 'free' argument, even if it starts with a dash. For example:
+//! `--brief -u9 -- plus.txt -.txt`
+
 //!
 //! # Usage
 //!