From d693d08a4baac124b0562d5ba88af783587c859c Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Thu, 12 Mar 2020 14:27:55 -0700
Subject: [PATCH] Update docs

---
 docs/arguments.md | 16 ++++++++++++----
 docs/options.md   | 28 ++++++++++++++++++++++++----
 2 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/docs/arguments.md b/docs/arguments.md
index a58254a04..da431838f 100644
--- a/docs/arguments.md
+++ b/docs/arguments.md
@@ -56,13 +56,13 @@ functions like [`pair`][pair] and [`triple`][triple]. Unlike options, arguments
 variable (or unlimited) number of values. This is common with file path arguments, since
 they are frequently expanded with a glob pattern on the command line.
 
-You can declare any number of arguments with fixed numbers of values,
-but only one variadic argument.
+Variadic arguments are declared with [`multiple`][multiple]. You can declare any number of arguments
+with fixed numbers of values, but only one variadic argument in a command.
 
 ```kotlin tab="Example"
 class Copy : CliktCommand() {
-    val source by argument().path(mustExist = true).multiple()
-    val dest by argument().path(canBeFile = false)
+    val source: List<Path> by argument().path(mustExist = true).multiple()
+    val dest: Path by argument().path(canBeFile = false)
     override fun run() {
         echo("Copying files $source to $dest")
     }
@@ -74,6 +74,12 @@ $ ./copy file.* out/
 Copying files [file.txt, file.md] to out/
 ```
 
+You can also use [`unique`][unique] to discard duplicates:
+
+```kotlin
+val source: Set<Path> by argument().path(mustExist = true).multiple().unique()
+```
+
 ## Option-Like Arguments (Using `--`)
 
 Clikt normally parses any value that starts with punctuation as an
@@ -114,3 +120,5 @@ bar.txt
 [argument]: api/clikt/com.github.ajalt.clikt.parameters.arguments/argument.md
 [pair]:     api/clikt/com.github.ajalt.clikt.parameters.arguments/pair.md
 [triple]:   api/clikt/com.github.ajalt.clikt.parameters.arguments/triple.md
+[unique]:   api/clikt/com.github.ajalt.clikt.parameters.arguments/unique.md
+[multiple]: api/clikt/com.github.ajalt.clikt.parameters.arguments/multiple.md
diff --git a/docs/options.md b/docs/options.md
index 9b14a0c25..3ec2f17fe 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -210,7 +210,7 @@ is never given, the list will be empty (or you can specify a default to use).
 
 ```kotlin tab="Example"
 class Commit : CliktCommand() {
-    val message by option("-m").multiple()
+    val message: List<String> by option("-m").multiple()
     override fun run() {
         echo(message.joinToString("\n"))
     }
@@ -224,22 +224,41 @@ bar
 ```
 
 You can combine [`multiple`][multiple] with item type conversions and multiple values.
-For example:
 
 ```kotlin
 val opt: List<Pair<Int, Int>> by option().int().pair().multiple()
 ```
 
+### Default values for option().multiple()
+
 You can also supply a default value to [`multiple`][multiple] or require at least one value be present
 on the command line. These are specified as arguments rather than with separate extension functions
 since they don't change the type of the delegate.
 
 ```kotlin tab="Required"
-val opt by option().multiple(required=true)
+val opt: List<String> by option().multiple(required=true)
 ```
 
 ```kotlin tab="Default"
-val opt by option().multiple(default=listOf("default message"))
+val opt: List<String> by option().multiple(default=listOf("default message"))
+```
+
+### Deduplicating option().multiple() into a unique set
+
+You can discard duplicate values from a `multiple` option with [`unique`][unique].
+
+```kotlin tab="Example"
+class Build : CliktCommand() {
+    val platforms: Set<String> by option("-p").multiple().unique()
+    override fun run() {
+        echo("Building for platforms: $platforms")
+    }
+}
+```
+
+```text tab="Usage"
+$ ./build -p android -p ios -p android
+Building for platforms: [android, ios]
 ```
 
 ## Boolean Flag Options
@@ -918,6 +937,7 @@ val opt: Pair<Int, Int> by option("-o", "--opt")
 [transformValues]:             api/clikt/com.github.ajalt.clikt.parameters.options/transform-values.md
 [default]:                     api/clikt/com.github.ajalt.clikt.parameters.options/default.md
 [multiple]:                    api/clikt/com.github.ajalt.clikt.parameters.options/multiple.md
+[unique]:                      api/clikt/com.github.ajalt.clikt.parameters.options/unique.md
 [defaultLazy]:                 api/clikt/com.github.ajalt.clikt.parameters.options/default-lazy.md
 [split]:                       api/clikt/com.github.ajalt.clikt.parameters.options/split.md
 [flag]:                        api/clikt/com.github.ajalt.clikt.parameters.options/flag.md