Add markdown documentation for unique faker

README.md

@@ -175,6 +175,16 @@ String json = Format.toJson(
 ```
 More complex examples and other formats like YAML, XML could be found at https://www.datafaker.net/documentation/file-formats/
 
+### Unique Values
+```java
+Faker faker = new Faker();
+
+// The values returned in the following lines will never be the same.
+String firstUniqueInstrument = faker.unique().fetchFromYaml("music.instruments"); // "Flute"
+String secondUniqueInstrument = faker.unique().fetchFromYaml("music.instruments"); // "Clarinet"
+```
+More examples can be found in https://www.datafaker.net/documentation/unique-values
+
 ### Custom provider
 Add your own custom provider in your app following steps from https://www.datafaker.net/documentation/custom-providers/
 

docs/documentation/unique-values.md

@@ -0,0 +1,37 @@
+# Unique Values
+
+## Values from YAML files
+
+Unique values can be retrieved from the YAML files by key, if the key references a hard-coded list of values.
+
+=== "Java"
+
+    ``` java 
+    Faker faker = new Faker();
+
+    // The values returned in the following lines will never be the same.
+    String firstUniqueInstrument = faker.unique().fetchFromYaml("music.instruments"); // "Flute"
+    String secondUniqueInstrument = faker.unique().fetchFromYaml("music.instruments"); // "Clarinet"
+    ```
+
+Note: Unique values are based on key and locale, so it's possible to get the same value if the locale is manually changed or if two different keys contain the same value.
+
+If all possible values have been returned, an exception will be thrown.
+
+=== "Java"
+
+    ``` java 
+    Faker faker = new Faker();
+    String firstUniqueInstrument = faker.unique().fetchFromYaml("music.instruments"); // "Ukelele"
+    ...
+    String nthUniqueInstrument = faker.unique().fetchFromYaml("music.instruments"); // throws NoSuchElementException
+    ```
+
+Any non-string values will be converted.
+
+=== "Java"
+
+    ``` java 
+    Faker faker = new Faker();
+    String successCode = faker.unique().fetchFromYaml("sip.response.codes.success")); // "200"
+    ```

mkdocs.yml

@@ -100,6 +100,7 @@ nav:
       - Custom providers: documentation/custom-providers.md
       - Expressions: documentation/expressions.md
       - File formats: documentation/file-formats.md
+      - Unique values: documentation/unique-values.md
     - Performance: documentation/performance.md
     - Javadoc: 'https://s01.oss.sonatype.org/service/local/repositories/releases/archive/net/datafaker/datafaker/1.5.0/datafaker-1.5.0-javadoc.jar/!/index.html'
     - Contributing: documentation/contributing.md