Clarify that cargo doc --no-deps is cumulative and won’t delete prev issue #15728

crates/build-rs/src/output.rs

@@ -119,6 +119,8 @@ pub fn rustc_link_arg_bins(flag: &str) {
 /// The `rustc-link-arg-tests` instruction tells Cargo to pass the
 /// [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building
 /// a tests target.
+///
+/// [link-arg]: https://doc.rust-lang.org/rustc/codegen-options/index.html#link-arg
 #[track_caller]
 pub fn rustc_link_arg_tests(flag: &str) {
     if flag.contains([' ', '\n']) {
@@ -130,6 +132,8 @@ pub fn rustc_link_arg_tests(flag: &str) {
 /// The `rustc-link-arg-examples` instruction tells Cargo to pass the
 /// [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building
 /// an examples target.
+///
+/// [link-arg]: https://doc.rust-lang.org/rustc/codegen-options/index.html#link-arg
 #[track_caller]
 pub fn rustc_link_arg_examples(flag: &str) {
     if flag.contains([' ', '\n']) {
@@ -141,6 +145,8 @@ pub fn rustc_link_arg_examples(flag: &str) {
 /// The `rustc-link-arg-benches` instruction tells Cargo to pass the
 /// [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building
 /// a benchmark target.
+///
+/// [link-arg]: https://doc.rust-lang.org/rustc/codegen-options/index.html#link-arg
 #[track_caller]
 pub fn rustc_link_arg_benches(flag: &str) {
     if flag.contains([' ', '\n']) {

src/cargo/core/compiler/rustdoc.rs

@@ -243,7 +243,7 @@ pub fn add_root_urls(
 }
 
 /// Adds unstable flag [`--output-format`][1] to the given `rustdoc`
-/// invocation. This is for unstable feature [`-Zunstable-features`].
+/// invocation. This is for unstable feature `-Zunstable-features`.
 ///
 /// [1]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html?highlight=output-format#-w--output-format-output-format
 pub fn add_output_format(

src/cargo/util/context/mod.rs

@@ -1982,7 +1982,7 @@ impl GlobalContext {
         Ok(())
     }
 
-    /// Returns a list of [target.'`cfg()`'] tables.
+    /// Returns a list of `target.'cfg()'` tables.
     ///
     /// The list is sorted by the table name.
     pub fn target_cfgs(&self) -> CargoResult<&Vec<(String, TargetCfgConfig)>> {

src/doc/man/cargo-doc.md

@@ -16,6 +16,8 @@ cargo-doc --- Build a package's documentation
 Build the documentation for the local package and all dependencies. The output
 is placed in `target/doc` in rustdoc's usual format.
 
+**Note:** Documentation generation is cumulative: existing doc files in the target directory are preserved across different cargo doc invocations. To remove existing generated docs, pass `--doc` to {{man "cargo-clean" 1}}.
+
 ## OPTIONS
 
 ### Documentation Options

src/doc/man/generated_txt/cargo-doc.txt

@@ -10,6 +10,10 @@ DESCRIPTION
        Build the documentation for the local package and all dependencies. The
        output is placed in target/doc in rustdoc’s usual format.
 
+       Note: Documentation generation is cumulative: existing doc files in the
+       target directory are preserved across different cargo doc invocations.
+       To remove existing generated docs, pass --doc to cargo-clean(1).
+
 OPTIONS
    Documentation Options
        --open

src/doc/src/commands/cargo-doc.md

@@ -12,6 +12,8 @@ cargo-doc --- Build a package's documentation
 Build the documentation for the local package and all dependencies. The output
 is placed in `target/doc` in rustdoc's usual format.
 
+**Note:** Documentation generation is cumulative: existing doc files in the target directory are preserved across different cargo doc invocations. To remove existing generated docs, pass `--doc` to [cargo-clean(1)](cargo-clean.html).
+
 ## OPTIONS
 
 ### Documentation Options

src/etc/man/cargo-doc.1

@@ -10,6 +10,8 @@ cargo\-doc \[em] Build a package\[cq]s documentation
 .SH "DESCRIPTION"
 Build the documentation for the local package and all dependencies. The output
 is placed in \fBtarget/doc\fR in rustdoc\[cq]s usual format.
+.sp
+\fBNote:\fR Documentation generation is cumulative: existing doc files in the target directory are preserved across different cargo doc invocations. To remove existing generated docs, pass \fB\-\-doc\fR to \fBcargo\-clean\fR(1).
 .SH "OPTIONS"
 .SS "Documentation Options"
 .sp