diff --git a/src/bin/cargo/commands/doc.rs b/src/bin/cargo/commands/doc.rs
index 009bd2bfa34..875cfcfcc46 100644
--- a/src/bin/cargo/commands/doc.rs
+++ b/src/bin/cargo/commands/doc.rs
@@ -20,10 +20,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 example",
+ "Document all examples",
)
.arg_release("Build artifacts in release mode, with optimizations")
.arg_profile("Build artifacts with the specified profile")
diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs
index 9e893928850..c99b8688f1e 100644
--- a/src/cargo/util/command_prelude.rs
+++ b/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)
- ._arg(optional_multi_opt("example", "NAME", example))
- ._arg(opt("examples", examples))
+ self.arg_targets_lib_bin_example(lib, bin, bins, example, examples)
._arg(optional_multi_opt("test", "NAME", test))
._arg(opt("tests", tests))
._arg(optional_multi_opt("bench", "NAME", bench))
@@ -97,10 +95,19 @@ 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(
diff --git a/src/doc/man/cargo-doc.md b/src/doc/man/cargo-doc.md
index d7c3dc7299c..b0289a8368f 100644
--- a/src/doc/man/cargo-doc.md
+++ b/src/doc/man/cargo-doc.md
@@ -52,6 +52,16 @@ flag and will always document the given target.
{{#options}}
{{> options-targets-lib-bin }}
+
+{{#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 example targets.
+{{/option}}
+
{{/options}}
{{> section-features }}
diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt
index 2b34fb93fc7..de1589d6304 100644
--- a/src/doc/man/generated_txt/cargo-doc.txt
+++ b/src/doc/man/generated_txt/cargo-doc.txt
@@ -82,6 +82,13 @@ OPTIONS
--bins
Document all binary targets.
+ --example name...
+ Document the specified example. This flag may be specified multiple
+ times and supports common Unix glob patterns.
+
+ --examples
+ Document all example targets.
+
Feature Selection
The feature flags allow you to control which features are enabled. When
no feature options are given, the default feature is activated for every
diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md
index 6f8255ca3ab..774169816c9 100644
--- a/src/doc/src/commands/cargo-doc.md
+++ b/src/doc/src/commands/cargo-doc.md
@@ -107,6 +107,16 @@ and supports common Unix glob patterns.
Document all binary targets.
+
+--example name...
+Document the specified example. This flag may be specified multiple times
+and supports common Unix glob patterns.
+
+
+--examples
+Document all example targets.
+
+
### Feature Selection
diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1
index 3d783b7547b..045795bb3ac 100644
--- a/src/etc/man/cargo-doc.1
+++ b/src/etc/man/cargo-doc.1
@@ -95,6 +95,17 @@ and supports common Unix glob patterns.
.RS 4
Document all binary targets.
.RE
+.sp
+\fB\-\-example\fR \fIname\fR\&...
+.RS 4
+Document the specified example. This flag may be specified multiple times
+and supports common Unix glob patterns.
+.RE
+.sp
+\fB\-\-examples\fR
+.RS 4
+Document all example targets.
+.RE
.SS "Feature Selection"
The feature flags allow you to control which features are enabled. When no
feature options are given, the \fBdefault\fR feature is activated for every
diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs
index 183420192b6..7ea15c36caa 100644
--- a/tests/testsuite/doc.rs
+++ b/tests/testsuite/doc.rs
@@ -513,6 +513,108 @@ 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()