docs: add desc field for stages and outs

Per iterative/dvc#4901

content/docs/command-reference/add.md

@@ -7,7 +7,7 @@ file.
 
 ```usage
 usage: dvc add [-h] [-q | -v] [-R] [--no-commit] [--external]
-               [--file <filename>] [--glob]
+               [--file <filename>] [--glob] [--desc <text>]
                targets [targets ...]
 
 positional arguments:
@@ -148,6 +148,9 @@ directory symlinks.
   pattern as specified by `target`. Shell-style wildcards are supported: `*`,
   `?`, `[seq]`, `[!seq]`, and `**`.
 
+- `--desc <text>` - user description of the data (optional). This doesn't affect
+  any DVC operations.
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no

content/docs/command-reference/import-url.md

@@ -11,6 +11,7 @@ changes in the remote data source. Creates a `.dvc` file.
 
 ```usage
 usage: dvc import-url [-h] [-q | -v] [--file <filename>] [--no-exec]
+                      [--desc <text>]
                       url [out]
 
 positional arguments:
@@ -129,6 +130,9 @@ source.
   `.dvc` file. You can use `dvc commit <out>.dvc` if you need the hashes in the
   new `.dvc` file and save existing data to the cache.
 
+- `--desc <text>` - user description of the data (optional). This doesn't  
+  affect any DVC operations.
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no

content/docs/command-reference/import.md

@@ -12,7 +12,7 @@ the import.
 ```usage
 usage: dvc import [-h] [-q | -v]
                   [-o <path>] [--file <filename>]
-                  [--rev <commit>] [--no-exec]
+                  [--rev <commit>] [--no-exec] [--desc <text>]
                   url path
 
 positional arguments:
@@ -109,6 +109,9 @@ repo at `url`) are not supported.
   is saved into the `.dvc` file. You can use `dvc commit <out>.dvc` if you need
   the hashes in the new `.dvc` file and save existing data to the cache.
 
+- `--desc <text>` - user description of the data (optional). This doesn't affect
+  any DVC operations.
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no

content/docs/command-reference/run.md

@@ -12,7 +12,7 @@ usage: dvc run [-h] [-q | -v] -n <name> [-d <path>] [-o <path>]
                [-w <path>] [--no-exec] [-f]
                [--no-run-cache] [--no-commit]
                [--outs-persist <path>] [--outs-persist-no-cache <path>]
-               [--always-changed] [--external]
+               [--always-changed] [--external] [--desc <text>]
                command
 
 positional arguments:
@@ -263,6 +263,9 @@ $ dvc run -n my_stage './my_script.sh $MYENVVAR'
 - `--external` - allow outputs that are outside of the DVC repository. See
   [Managing External Data](/doc/user-guide/managing-external-data).
 
+- `--desc <text>` - user description of the stage (optional). This doesn't  
+  affect any DVC operations.
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no

content/docs/user-guide/dvc-files-and-directories.md

@@ -37,6 +37,7 @@ edit, or even created manually. Here is a sample:
 outs:
   - md5: a304afb96060aad90176268345e10355
     path: data.xml
+    desc: cats and dogs dataset
 
 # Comments and user metadata are supported.
 meta:
@@ -74,6 +75,8 @@ An _output entry_ (`outs`) consists of these fields:
 - `nfiles`: If a directory, number of files inside.
 - `cache`: Whether or not this file or directory is <abbr>cached</abbr> (`true`
   by default, if not present). See the `--no-commit` option of `dvc add`.
+- `meta`: User description for this output. This doesn't affect any DVC
+  operations.
 
 A _dependency entry_ (`deps`) consists of these fields:
 
@@ -128,12 +131,14 @@ stages:
     metrics:
       - performance.json
   training:
+    desc: train your model
     cmd: python train.py
     deps:
       - train.py
       - features
     outs:
-      - model.pkl
+      - model.pkl:
+          desc: my model description
     plots:
       - logs.csv:
           x: epoch
@@ -173,6 +178,8 @@ the possible following fields:
 - `meta` (optional): Arbitrary metadata can be added manually with this field.
   Any YAML contents is supported. `meta` contents are ignored by DVC, but they
   can be meaningful for user processes that read or write `.dvc` files directly.
+- `desc` (optional): User description for this stage. This doesn't affect any
+  DVC operations.
 
 `dvc.yaml` files also support `# comments`.