Repository: iterative/dvc

Issue:
metrics & plots: help output improvements [qa]
### Please provide information about your setup

DVC 1.0.0a6+283718

### Report

```console
λ dvc metrics -h
usage: dvc metrics [-h] [-q | -v] {add,show,diff,remove} ...

Commands to add, manage, collect, and display metrics.
Documentation: <https://man.dvc.org/metrics>

positional arguments:
  {add,show,diff,remove}
                        Use `dvc metrics CMD --help` to display command-specific help.
    add                 Mark a DVC-tracked file as a metric.
    show                Print metrics, with optional formatting.
    diff                Show changes in metrics between commits
    remove              Remove metric mark on a DVC-tracked file.
```
- [x] remove `add` and `remove`
- [x] desc: "Commands to display and compare metrics."
- [x] diff: "Show changes in metrics between commits." (add period: it's a full sentence)

```console
λ dvc metrics show -h
usage: dvc metrics show ...

positional arguments:
  targets             Metric files or directories (see -R) to show
```
- [x] `targets`: "Metric files ~~or directories (see -R)~~ to show" https://github.com/iterative/dvc/pull/3935

```console
λ dvc metrics diff -h
usage: dvc metrics diff ...

Show changes in metrics between commits
Documentation: ...
```
- "Show changes in metrics between commits." (end in period)

---

```console
λ dvc plots -h
usage: dvc plots [-h] [-q | -v] {show,diff} ...

Generating plots for metrics stored in structured files (JSON, CSV, TSV).
Documentation: <https://man.dvc.org/plots>

positional arguments:
  {show,diff}    Use `dvc plots CMD --help` to display command-specific help.
    show         Generate a plots image file from a metrics file.
    diff         Plot differences in metrics between commits in the DVC repository, or between the last commit and the workspace.
```
- desc: "Commands to visualize and compare plot metrics in structured files (JSON, CSV, TSV)."
- `show`: "Generate plot from a metrics file."
- `diff`: "Plot differences in metrics between commits."

```console
λ dvc plots show -h
usage: dvc plots show [-h] [-q | -v] [-t [TEMPLATE]] [-o OUT] [-x X] [-y Y] [--no-csv-header] [--show-json] [--title TITLE] [--xlab XLAB]
                      [--ylab YLAB]
                      [targets [targets ...]]

Generate a plots image file from a metrics file.
Documentation: <https://man.dvc.org/plots/show>

positional arguments:
  targets               Metrics files to visualize. Shows all plots by default.
```
- desc: "Generate plot from a metrics file."
- ~~`targets`: why is it printed as optional? The command actually requires it.~~ See #3925
- option arguments from `UPPER_CASE` to `<type_format>`. Probably:
  + TEMPLATE -> `<path>`
  + OUT -> `<path>`
  + X/Y -> `<field>`
  + TITLE -> `<text>`
  + XLAB/YLAB -> `<text>`

```console
λ dvc plots diff -h
usage: dvc plots diff [-h] [-q | -v] [-t [TEMPLATE]] [--targets [TARGETS [TARGETS ...]]] [-o OUT] [-x X] [-y Y] [--no-csv-header] [--show-json]
                      [--title TITLE] [--xlab XLAB] [--ylab YLAB]
                      [revisions [revisions ...]]

Plot differences in metrics between commits in the DVC repository, or between the last commit and the workspace.
Documentation: <https://man.dvc.org/plots/diff>

positional arguments:
  revisions             Git commits to plot from
```
- desc: "Plot differences in metrics between commits."
- option arguments from ... Same as previous command plus:
  + TARGETS -> `<path>`
- `revisions`: "Git commits to plot from/to"

> Note that all these are already being applied to docs in iterative/dvc.org/pull/1360 and iterative/dvc.org/pull/1382

UPDATE: Similar updates apply to `plots modify` now that it has been added.

---

EXTRA: Additionally it would be nice to reorder the command parameters to match the order in the Options sections of the corresponding published cmd refs.


Discussion:
p.s. sorry I don't currently have the capacity to work on this, otherwise I would've sent a PR instead.
**NOTE:** We also have `dvc plots modify` now, not sure it should be advertised though as it doesn't have the full functionality yet - no support for multiple plots per plot file. Also, `dvc plots add/delete` commands are still missing.

Resolving patch:
diff --git a/dvc/command/metrics.py b/dvc/command/metrics.py
--- a/dvc/command/metrics.py
+++ b/dvc/command/metrics.py
@@ -165,7 +165,10 @@ def add_parser(subparsers, parent_parser):
     metrics_show_parser.add_argument(
         "targets",
         nargs="*",
-        help="Metric files or directories (see -R) to show",
+        help=(
+            "Limit command scope to these metric files. Using -R, "
+            "directories to search metric files in can also be given."
+        ),
     )
     metrics_show_parser.add_argument(
         "-a",
@@ -187,6 +190,12 @@ def add_parser(subparsers, parent_parser):
         default=False,
         help="Show metrics for all commits.",
     )
+    metrics_show_parser.add_argument(
+        "--show-json",
+        action="store_true",
+        default=False,
+        help="Show output in JSON format.",
+    )
     metrics_show_parser.add_argument(
         "-R",
         "--recursive",
@@ -197,12 +206,6 @@ def add_parser(subparsers, parent_parser):
             "metric files."
         ),
     )
-    metrics_show_parser.add_argument(
-        "--show-json",
-        action="store_true",
-        default=False,
-        help="Show output in JSON format.",
-    )
     metrics_show_parser.set_defaults(func=CmdMetricsShow)
 
     METRICS_DIFF_HELP = (
@@ -222,14 +225,14 @@ def add_parser(subparsers, parent_parser):
     metrics_diff_parser.add_argument(
         "b_rev",
         nargs="?",
-        help=("New Git commit to compare (defaults to the current workspace)"),
+        help="New Git commit to compare (defaults to the current workspace)",
     )
     metrics_diff_parser.add_argument(
         "--targets",
         nargs="*",
         help=(
-            "Metric files or directories (see -R) to show diff for. "
-            "Shows diff for all metric files by default."
+            "Limit command scope to these metric files. Using -R, "
+            "directories to search metric files in can also be given."
         ),
         metavar="<paths>",
     )
@@ -262,16 +265,16 @@ def add_parser(subparsers, parent_parser):
         help="Show tabulated output in the Markdown format (GFM).",
     )
     metrics_diff_parser.add_argument(
-        "--no-path",
+        "--old",
         action="store_true",
         default=False,
-        help="Don't show metric path.",
+        help="Show old metric value.",
     )
     metrics_diff_parser.add_argument(
-        "--old",
+        "--no-path",
         action="store_true",
         default=False,
-        help="Show old metric value.",
+        help="Don't show metric path.",
     )
     metrics_diff_parser.add_argument(
         "--precision",
diff --git a/dvc/command/plots.py b/dvc/command/plots.py
--- a/dvc/command/plots.py
+++ b/dvc/command/plots.py
@@ -98,8 +98,8 @@ def run(self):
 
 def add_parser(subparsers, parent_parser):
     PLOTS_HELP = (
-        "Generating plots for metrics stored in structured files "
-        "(JSON, CSV, TSV)."
+        "Commands to visualize and compare plot metrics in structured files "
+        "(JSON, YAML, CSV, TSV)"
     )
 
     plots_parser = subparsers.add_parser(
@@ -116,7 +116,7 @@ def add_parser(subparsers, parent_parser):
 
     fix_subparsers(plots_subparsers)
 
-    SHOW_HELP = "Generate a plots image file from a metrics file."
+    SHOW_HELP = "Generate plots from metric files."
     plots_show_parser = plots_subparsers.add_parser(
         "show",
         parents=[parent_parser],
@@ -134,8 +134,8 @@ def add_parser(subparsers, parent_parser):
     plots_show_parser.set_defaults(func=CmdPlotsShow)
 
     PLOTS_DIFF_HELP = (
-        "Plot differences in metrics between commits in the DVC "
-        "repository, or between the last commit and the workspace."
+        "Show multiple versions of plot metrics "
+        "by plotting them in a single image."
     )
     plots_diff_parser = plots_subparsers.add_parser(
         "diff",
@@ -148,6 +148,7 @@ def add_parser(subparsers, parent_parser):
         "--targets",
         nargs="*",
         help="Plots file to visualize. Shows all plots by default.",
+        metavar="<path>",
     )
     plots_diff_parser.add_argument(
         "revisions", nargs="*", default=None, help="Git commits to plot from",
@@ -156,7 +157,7 @@ def add_parser(subparsers, parent_parser):
     _add_output_arguments(plots_diff_parser)
     plots_diff_parser.set_defaults(func=CmdPlotsDiff)
 
-    PLOTS_MODIFY_HELP = "Modify plot properties associated with a target file."
+    PLOTS_MODIFY_HELP = "Modify display properties of plot metric files."
     plots_modify_parser = plots_subparsers.add_parser(
         "modify",
         parents=[parent_parser],
@@ -165,14 +166,14 @@ def add_parser(subparsers, parent_parser):
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     plots_modify_parser.add_argument(
-        "target", help="Plot file to set properties to.",
+        "target", help="Metric file to set properties to",
     )
     _add_props_arguments(plots_modify_parser)
     plots_modify_parser.add_argument(
         "--unset",
         nargs="*",
         metavar="<property>",
-        help="Properties to unset.",
+        help="Unset one or more display properties.",
     )
     plots_modify_parser.set_defaults(func=CmdPlotsModify)
 
@@ -189,9 +190,14 @@ def _add_props_arguments(parser):
                 format_link("https://man.dvc.org/plots#plot-templates")
             )
         ),
+        metavar="<path>",
+    )
+    parser.add_argument(
+        "-x", default=None, help="Field name for X axis.", metavar="<field>"
+    )
+    parser.add_argument(
+        "-y", default=None, help="Field name for Y axis.", metavar="<field>"
     )
-    parser.add_argument("-x", default=None, help="Field name for x axis.")
-    parser.add_argument("-y", default=None, help="Field name for y axis.")
     parser.add_argument(
         "--no-header",
         action="store_false",
@@ -203,16 +209,20 @@ def _add_props_arguments(parser):
         "--title", default=None, metavar="<text>", help="Plot title."
     )
     parser.add_argument(
-        "--x-label", default=None, metavar="<text>", help="X axis label."
+        "--x-label", default=None, help="X axis label", metavar="<text>"
     )
     parser.add_argument(
-        "--y-label", default=None, metavar="<text>", help="Y axis lebel."
+        "--y-label", default=None, help="Y axis label", metavar="<text>"
     )
 
 
 def _add_output_arguments(parser):
     parser.add_argument(
-        "-o", "--out", default=None, help="Destination path to save plots to.",
+        "-o",
+        "--out",
+        default=None,
+        help="Destination path to save plots to",
+        metavar="<path>",
     )
     parser.add_argument(
         "--show-vega",


Test patch: