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,11 +52,22 @@ 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 during migration, instead of fixing everything
+in a single `cargo fix` invocation, try fixing only a subset of packages for
+specific features and Cargo targets. Fixing each combination separately can
+help identify the root cause of failures more easily and avoid unintended
+feature unification between packages. For example:
+
+* Use the `--package` flag to fix only some packages, e.g., `cargo fix --package foo`.
+* Instead of `--all-features`, use the `--features` flag to activate a specific
+  set of features, e.g., `cargo fix --package foo --features myfeat`.
+* `cargo fix` implies `--all-targets` by default. Use target selection flags to
+  fix only a subset of Cargo targets, e.g., `cargo fix --bin mybin`.
+
+Also 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.
 
 [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

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

@@ -53,11 +53,29 @@ 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 during migration, instead of fixing
+       everything in a single cargo fix invocation, try fixing only a subset of
+       packages for specific features and Cargo targets. Fixing each
+       combination separately can help identify the root cause of failures more
+       easily and avoid unintended feature unification between packages. For
+       example:
+
+       o  Use the --package flag to fix only some packages, e.g., cargo fix
+          --package foo.
+
+       o  Instead of --all-features, use the --features flag to activate a
+          specific set of features, e.g., cargo fix --package foo --features
+          myfeat.
+
+       o  cargo fix implies --all-targets by default. Use target selection
+          flags to fix only a subset of Cargo targets, e.g., cargo fix --bin
+          mybin.
+
+       Also 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,11 +48,22 @@ 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 during migration, instead of fixing everything
+in a single `cargo fix` invocation, try fixing only a subset of packages for
+specific features and Cargo targets. Fixing each combination separately can
+help identify the root cause of failures more easily and avoid unintended
+feature unification between packages. For example:
+
+* Use the `--package` flag to fix only some packages, e.g., `cargo fix --package foo`.
+* Instead of `--all-features`, use the `--features` flag to activate a specific
+  set of features, e.g., `cargo fix --package foo --features myfeat`.
+* `cargo fix` implies `--all-targets` by default. Use target selection flags to
+  fix only a subset of Cargo targets, e.g., `cargo fix --bin mybin`.
+
+Also 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.
 
 [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

src/etc/man/cargo-fix.1

@@ -64,11 +64,30 @@ 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 during migration, instead of fixing everything
+in a single \fBcargo fix\fR invocation, try fixing only a subset of packages for
+specific features and Cargo targets. Fixing each combination separately can
+help identify the root cause of failures more easily and avoid unintended
+feature unification between packages. For example:
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Use the \fB\-\-package\fR flag to fix only some packages, e.g., \fBcargo fix \-\-package foo\fR\&.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Instead of \fB\-\-all\-features\fR, use the \fB\-\-features\fR flag to activate a specific
+set of features, e.g., \fBcargo fix \-\-package foo \-\-features myfeat\fR\&.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'\fBcargo fix\fR implies \fB\-\-all\-targets\fR by default. Use target selection flags to
+fix only a subset of Cargo targets, e.g., \fBcargo fix \-\-bin mybin\fR\&.
+.RE
+.sp
+Also 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