add --examples subcommand

src/bin/cargo/commands/doc.rs

@@ -21,10 +21,12 @@ pub fn cli() -> App {
         .arg(opt("no-deps", "Don't build documentation for dependencies"))
         .arg(opt("document-private-items", "Document private items"))
         .arg_jobs()
-        .arg_targets_lib_bin(
+        .arg_targets_lib_bin_example(
             "Document only this package's library",
             "Document only the specified binary",
             "Document all binaries",
+            "Document only the specified binary",
+            "Document all examples",
         )
         .arg_release("Build artifacts in release mode, with optimizations")
         .arg_profile("Build artifacts with the specified profile")

src/cargo/util/command_prelude.rs

@@ -87,9 +87,7 @@ pub trait AppExt: Sized {
         benches: &'static str,
         all: &'static str,
     ) -> Self {
-        self.arg_targets_lib_bin(lib, bin, bins)
+        self.arg_targets_lib_bin_example(lib, bin, bins, example, examples)
-            ._arg(optional_multi_opt("example", "NAME", example))
-            ._arg(opt("examples", examples))
             ._arg(optional_multi_opt("test", "NAME", test))
             ._arg(opt("tests", tests))
             ._arg(optional_multi_opt("bench", "NAME", bench))
@@ -97,10 +95,12 @@ pub trait AppExt: Sized {
             ._arg(opt("all-targets", all))
     }
 
-    fn arg_targets_lib_bin(self, lib: &'static str, bin: &'static str, bins: &'static str) -> Self {
+    fn arg_targets_lib_bin_example(self, lib: &'static str, bin: &'static str, bins: &'static str, example: &'static str, examples: &'static str) -> Self {
         self._arg(opt("lib", lib))
             ._arg(optional_multi_opt("bin", "NAME", bin))
             ._arg(opt("bins", bins))
+            ._arg(optional_multi_opt("example", "NAME", example))
+            ._arg(opt("examples", examples))
     }
 
     fn arg_targets_bins_examples(

src/doc/man/cargo-doc.md

@@ -51,7 +51,7 @@ the manifest settings. Using target selection options will ignore the `doc`
 flag and will always document the given target.
 
 {{#options}}
-{{> options-targets-lib-bin }}
+{{> options-targets-lib-bin-example }}
 {{/options}}
 
 {{> section-features }}

src/doc/man/includes/options-targets-lib-bin-example.md

@@ -10,3 +10,13 @@ and supports common Unix glob patterns.
 {{#option "`--bins`" }}
 {{actionverb}} all binary targets.
 {{/option}}
+
+{{#option "`--example` _name_..." }}
+{{actionverb}} the specified example. This flag may be specified multiple times
+and supports common Unix glob patterns.
+{{/option}}
+
+{{#option "`--examples`" }}
+{{actionverb}} all examples targets.
+{{/option}}
+

tests/testsuite/doc.rs

@@ -513,6 +513,109 @@ fn doc_lib_bin_same_name_documents_bins_when_requested() {
     assert!(doc_html.contains("Binary"));
 }
 
+#[cargo_test]
+fn doc_lib_bin_example_same_name_documents_named_example_when_requested() {
+    let p = project()
+        .file(
+            "src/main.rs",
+            r#"
+                //! Binary documentation
+                extern crate foo;
+                fn main() {
+                    foo::foo();
+                }
+            "#,
+        )
+        .file(
+            "src/lib.rs",
+            r#"
+                //! Library documentation
+                pub fn foo() {}
+            "#,
+        )
+        .file(
+            "examples/ex1.rs",
+            r#"
+                //! Example1 documentation
+                pub fn x() { f(); }
+            "#,
+        )
+        .build();
+
+    p.cargo("doc --example ex1")
+        .with_stderr(
+            "\
+[CHECKING] foo v0.0.1 ([CWD])
+[DOCUMENTING] foo v0.0.1 ([CWD])
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]",
+        )
+        .run();
+
+    let doc_html = p.read_file("target/doc/ex1/index.html");
+    assert!(!doc_html.contains("Library"));
+    assert!(!doc_html.contains("Binary"));
+    assert!(doc_html.contains("Example1"));
+}
+
+#[cargo_test]
+fn doc_lib_bin_example_same_name_documents_examples_when_requested() {
+    let p = project()
+        .file(
+            "src/main.rs",
+            r#"
+                //! Binary documentation
+                extern crate foo;
+                fn main() {
+                    foo::foo();
+                }
+            "#,
+        )
+        .file(
+            "src/lib.rs",
+            r#"
+                //! Library documentation
+                pub fn foo() {}
+            "#,
+        )
+        .file(
+            "examples/ex1.rs",
+            r#"
+                //! Example1 documentation
+                pub fn example1() { f(); }
+            "#,
+        )
+        .file(
+            "examples/ex2.rs",
+            r#"
+                //! Example2 documentation
+                pub fn example2() { f(); }
+            "#,
+        )
+        .build();
+
+        p.cargo("doc --examples")
+        .with_stderr(
+            "\
+[CHECKING] foo v0.0.1 ([CWD])
+[DOCUMENTING] foo v0.0.1 ([CWD])
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]",
+        )
+        .run();
+
+    let example_doc_html_1 = p.read_file("target/doc/ex1/index.html");
+    let example_doc_html_2 = p.read_file("target/doc/ex2/index.html");
+
+    assert!(!example_doc_html_1.contains("Library"));
+    assert!(!example_doc_html_1.contains("Binary"));
+
+    assert!(!example_doc_html_2.contains("Library"));
+    assert!(!example_doc_html_2.contains("Binary"));
+
+    assert!(example_doc_html_1.contains("Example1"));
+    assert!(example_doc_html_2.contains("Example2"));
+}
+
+
 #[cargo_test]
 fn doc_dash_p() {
     let p = project()