Auto merge of #10770 - wmstack:master, r=weihanglo

Indicate how Cargo locates the manifest

Currently the only place where that is documented is in an obscure flag called `--manifest-path`. The behaviour of Cargo in regards to locating the manifest should be in a more obvious place, and this seems to be right about where I added it.

src/doc/man/cargo-locate-project.md

@@ -10,8 +10,14 @@ cargo-locate-project - Print a JSON representation of a Cargo.toml file's locati
 
 ## DESCRIPTION
 
-This command will print a JSON object to stdout with the full path to the
-`Cargo.toml` manifest.
+This command will print a JSON object to stdout with the full path to the manifest. The
+manifest is found by searching upward for a file named `Cargo.toml` starting from the current
+working directory.
+
+If the project happens to be a part of a workspace, the manifest of the project, rather than
+the workspace root, is output. This can be overriden by the `--workspace` flag. The root
+workspace is found by traversing further upward or by using the field `package.workspace` after
+locating the manifest of a workspace member.
 
 ## OPTIONS
 

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

@@ -9,7 +9,14 @@ SYNOPSIS
 
 DESCRIPTION
        This command will print a JSON object to stdout with the full path to
-       the Cargo.toml manifest.
+       the manifest. The manifest is found by searching upward for a file named
+       Cargo.toml starting from the current working directory.
+
+       If the project happens to be a part of a workspace, the manifest of the
+       project, rather than the workspace root, is output. This can be
+       overriden by the --workspace flag. The root workspace is found by
+       traversing further upward or by using the field package.workspace after
+       locating the manifest of a workspace member.
 
 OPTIONS
        --workspace

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

@@ -10,8 +10,14 @@ cargo-locate-project - Print a JSON representation of a Cargo.toml file's locati
 
 ## DESCRIPTION
 
-This command will print a JSON object to stdout with the full path to the
-`Cargo.toml` manifest.
+This command will print a JSON object to stdout with the full path to the manifest. The
+manifest is found by searching upward for a file named `Cargo.toml` starting from the current
+working directory.
+
+If the project happens to be a part of a workspace, the manifest of the project, rather than
+the workspace root, is output. This can be overriden by the `--workspace` flag. The root
+workspace is found by traversing further upward or by using the field `package.workspace` after
+locating the manifest of a workspace member.
 
 ## OPTIONS
 

src/doc/src/reference/manifest.md

@@ -1,7 +1,10 @@
 ## The Manifest Format
 
 The `Cargo.toml` file for each package is called its *manifest*. It is written
-in the [TOML] format. Every manifest file consists of the following sections:
+in the [TOML] format. It contains metadata that is needed to compile the package. Checkout
+the `cargo locate-project` section for more detail on how cargo finds the manifest file.
+
+Every manifest file consists of the following sections:
 
 * [`cargo-features`](unstable.md) — Unstable, nightly-only features.
 * [`[package]`](#the-package-section) — Defines a package.

src/etc/man/cargo-locate-project.1

@@ -8,8 +8,14 @@ cargo\-locate\-project \- Print a JSON representation of a Cargo.toml file's loc
 .SH "SYNOPSIS"
 \fBcargo locate\-project\fR [\fIoptions\fR]
 .SH "DESCRIPTION"
-This command will print a JSON object to stdout with the full path to the
-\fBCargo.toml\fR manifest.
+This command will print a JSON object to stdout with the full path to the manifest. The
+manifest is found by searching upward for a file named \fBCargo.toml\fR starting from the current
+working directory.
+.sp
+If the project happens to be a part of a workspace, the manifest of the project, rather than
+the workspace root, is output. This can be overriden by the \fB\-\-workspace\fR flag. The root
+workspace is found by traversing further upward or by using the field \fBpackage.workspace\fR after
+locating the manifest of a workspace member.
 .SH "OPTIONS"
 .sp
 \fB\-\-workspace\fR