Clarify that cargo doc --no-deps is cumulative and won’t delete prior docs

Author: ojuschugh1

src/doc/man/cargo-doc.md

@@ -31,6 +31,15 @@ option.
 
 {{#option "`--no-deps`" }}
 Do not build documentation for dependencies.
+
+**Note:** Documentation is _cumulative_. If you’ve already run
+`cargo doc` (including dependency docs), and later run
+`cargo doc --no-deps`, Cargo will skip deleting or rebuilding those
+old dependency docs. To remove them, you can either:
+
+1. Run `cargo clean --doc` before `cargo doc --no-deps`, or  
+2. Manually delete the unwanted folders under `target/doc/`.
+
 {{/option}}
 
 {{#option "`--document-private-items`" }}

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

@@ -26,8 +26,18 @@ option.</dd>
 
 
 <dt class="option-term" id="option-cargo-doc---no-deps"><a class="option-anchor" href="#option-cargo-doc---no-deps"></a><code>--no-deps</code></dt>
-<dd class="option-desc">Do not build documentation for dependencies.</dd>
-
+<dd class="option-desc">
+  Do not build documentation for dependencies.
+
+  <p><strong>Note:</strong> Cargo keeps docs cumulatively. If you’ve already run
+  <code>cargo doc</code> (which generated dependency docs), then later run
+  <code>cargo doc --no-deps</code>, Cargo will skip rebuilding (and won’t delete)
+  those existing docs. To truly remove old dependency docs, either:
+
+  1. Run <code>cargo clean --doc</code> before <code>cargo doc --no-deps</code>, or  
+  2. Manually delete the unwanted folders under <code>target/doc/</code>.
+  </p>
+</dd>
 
 <dt class="option-term" id="option-cargo-doc---document-private-items"><a class="option-anchor" href="#option-cargo-doc---document-private-items"></a><code>--document-private-items</code></dt>
 <dd class="option-desc">Include non-public items in the documentation. This will be enabled by default if documenting a binary target.</dd>