docs(cargo-fix): troubleshooting failing fixes

There are a couple of reasons taht `cargo fix` fails.
This doc update lists some approaches to narrow the scope
to help users deal with those failures one by one.

Author: weihanglo

src/doc/man/cargo-fix.md

@@ -52,15 +52,37 @@ The `cargo fix` subcommand can also be used to migrate a package from one
    (without the `--edition` flag) to apply any suggestions given by the
    compiler.
 
-And hopefully that's it! Just keep in mind of the caveats mentioned above that
-`cargo fix` cannot update code for inactive features or `cfg` expressions.
-Also, in some rare cases the compiler is unable to automatically migrate all
-code to the new edition, and this may require manual changes after building
-with the new edition.
+If you encounter failing fixes, read the troubleshooting section.
 
 [edition]: https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html
 [edition field]: ../reference/manifest.html#the-edition-field
 
+### Troubleshooting failing fixes
+
+While `cargo fix` strives to automatically apply fixes, it can still fail for
+various reasons. Here are some suggestions for troubleshooting fix failures:
+
+* Unlike other commands, `cargo fix` implies `--all-targets` by default.
+  Try fixing one Cargo target at a time instead of everything in one run.
+  For instance, narrow the scope to a single binary target:
+
+  ```sh
+  cargo fix --bin mybin
+  ```
+
+* If you have a Cargo workspace containing multiple packages,
+  fix them one by one to avoid unwanted feature unification between packages.
+  For instance, fix only the `bar` package :
+
+  ```sh
+  cargo fix --package bar
+  ```
+
+Keep in mind of the caveats mentioned above that `cargo fix` cannot update code
+for inactive features or `cfg` expressions. Also, in some rare cases the
+compiler is unable to automatically migrate all code to the new edition,
+and this may require manual changes after building with the new edition.
+
 ## OPTIONS
 
 ### Fix options

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

@@ -53,11 +53,30 @@ DESCRIPTION
           (without the --edition flag) to apply any suggestions given by the
           compiler.
 
-       And hopefully that’s it! Just keep in mind of the caveats mentioned
-       above that cargo fix cannot update code for inactive features or cfg
-       expressions. Also, in some rare cases the compiler is unable to
-       automatically migrate all code to the new edition, and this may require
-       manual changes after building with the new edition.
+       If you encounter failing fixes, read the troubleshooting section.
+
+   Troubleshooting failing fixes
+       While cargo fix strives to automatically apply fixes, it can still fail
+       for various reasons. Here are some suggestions for troubleshooting fix
+       failures:
+
+       o  Unlike other commands, cargo fix implies --all-targets by default.
+          Try fixing one Cargo target at a time instead of everything in one
+          run. For instance, narrow the scope to a single binary target:
+
+              cargo fix --bin mybin
+
+       o  If you have a Cargo workspace containing multiple packages, fix them
+          one by one to avoid unwanted feature unification between packages.
+          For instance, fix only the bar package :
+
+              cargo fix --package bar
+
+       Keep in mind of the caveats mentioned above that cargo fix cannot update
+       code for inactive features or cfg expressions. Also, in some rare cases
+       the compiler is unable to automatically migrate all code to the new
+       edition, and this may require manual changes after building with the new
+       edition.
 
 OPTIONS
    Fix options

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

@@ -48,15 +48,37 @@ The `cargo fix` subcommand can also be used to migrate a package from one
    (without the `--edition` flag) to apply any suggestions given by the
    compiler.
 
-And hopefully that's it! Just keep in mind of the caveats mentioned above that
-`cargo fix` cannot update code for inactive features or `cfg` expressions.
-Also, in some rare cases the compiler is unable to automatically migrate all
-code to the new edition, and this may require manual changes after building
-with the new edition.
+If you encounter failing fixes, read the troubleshooting section.
 
 [edition]: https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html
 [edition field]: ../reference/manifest.html#the-edition-field
 
+### Troubleshooting failing fixes
+
+While `cargo fix` strives to automatically apply fixes, it can still fail for
+various reasons. Here are some suggestions for troubleshooting fix failures:
+
+* Unlike other commands, `cargo fix` implies `--all-targets` by default.
+  Try fixing one Cargo target at a time instead of everything in one run.
+  For instance, narrow the scope to a single binary target:
+
+  ```sh
+  cargo fix --bin mybin
+  ```
+
+* If you have a Cargo workspace containing multiple packages,
+  fix them one by one to avoid unwanted feature unification between packages.
+  For instance, fix only the `bar` package :
+
+  ```sh
+  cargo fix --package bar
+  ```
+
+Keep in mind of the caveats mentioned above that `cargo fix` cannot update code
+for inactive features or `cfg` expressions. Also, in some rare cases the
+compiler is unable to automatically migrate all code to the new edition,
+and this may require manual changes after building with the new edition.
+
 ## OPTIONS
 
 ### Fix options

src/etc/man/cargo-fix.1

@@ -64,11 +64,39 @@ warnings are issued, you may want to consider running \fBcargo fix\fR again
 compiler.
 .RE
 .sp
-And hopefully that\[cq]s it! Just keep in mind of the caveats mentioned above that
-\fBcargo fix\fR cannot update code for inactive features or \fBcfg\fR expressions.
-Also, in some rare cases the compiler is unable to automatically migrate all
-code to the new edition, and this may require manual changes after building
-with the new edition.
+If you encounter failing fixes, read the troubleshooting section.
+.SS "Troubleshooting failing fixes"
+While \fBcargo fix\fR strives to automatically apply fixes, it can still fail for
+various reasons. Here are some suggestions for troubleshooting fix failures:
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Unlike other commands, \fBcargo fix\fR implies \fB\-\-all\-targets\fR by default.
+Try fixing one Cargo target at a time instead of everything in one run.
+For instance, narrow the scope to a single binary target:
+.sp
+.RS 4
+.nf
+cargo fix \-\-bin mybin
+.fi
+.RE
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'If you have a Cargo workspace containing multiple packages,
+fix them one by one to avoid unwanted feature unification between packages.
+For instance, fix only the \fBbar\fR package :
+.sp
+.RS 4
+.nf
+cargo fix \-\-package bar
+.fi
+.RE
+.RE
+.sp
+Keep in mind of the caveats mentioned above that \fBcargo fix\fR cannot update code
+for inactive features or \fBcfg\fR expressions. Also, in some rare cases the
+compiler is unable to automatically migrate all code to the new edition,
+and this may require manual changes after building with the new edition.
 .SH "OPTIONS"
 .SS "Fix options"
 .sp