doc: clarify--why command

Author: tgolsson

docs/cli.md

@@ -444,7 +444,7 @@ required by
 ### Options
 
 * `--without`: The dependency groups to ignore.
-* `--why`: Include reverse dependencies where applicable.
+* `--why`: When showing the full list, or a `--tree` for a single package, display why a package is included.
 * `--with`: The optional dependency groups to include.
 * `--only`: The only dependency groups to include.
 * `--default`: Only include the main dependencies. (**Deprecated**)
@@ -457,6 +457,7 @@ required by
 When `--only` is specified, `--with` and `--without` options are ignored.
 {{% /note %}}
 
+
 ## build
 
 The `build` command builds the source and wheels archives.

src/poetry/console/commands/show.py

@@ -50,7 +50,8 @@ class ShowCommand(GroupCommand):
         option(
             "why",
             None,
-            "When listing the tree for a single package, start from parents.",
+            "When showing the full list, or a <info>--tree</info> for a single package,"
+            " also display why it's included.",
         ),
         option("latest", "l", "Show the latest version."),
         option(