t Added docs and examples for namers

Author: ScottBob

approvaltests-tests/src/test/java/org/approvaltests/namer/NamerFactoryForOptionsTest.exampleForDocs.title.chapter.approved.txt

@@ -0,0 +1 @@
+data

approvaltests-tests/src/test/java/org/approvaltests/namer/NamerFactoryForOptionsTest.java

@@ -21,15 +21,33 @@ void testOsSpecificTest()
     String name = namer.getApprovedFile(".txt").getName();
     assertEquals("NamerFactoryForOptionsTest.testOsSpecificTest.Mac_OS_X.approved.txt", name);
   }
+  @Test
+  void oldExampleForDocs()
+  {
+    // begin-snippet: namer_factory_example
+    try (NamedEnvironment namer = NamerFactory.withParameters("title", "chapter")) {
+      Approvals.verify("data");
+    }
+    // end-snippet
+  }
+  @Test
+  void exampleForDocs()
+  {
+    // begin-snippet: additional_information_example
+    Approvals.verify("data", Approvals.NAMES.withParameters("title", "chapter"));
+    // end-snippet
+  }
   @Disabled("TODO: only on Lars' laptop")
   //  @EnabledOnOs(OS.MAC)
   @Test
   void testMachineSpecificTestAndOsSPecific()
   {
+    // begin-snippet: options_and
     Options options = Approvals.NAMES.asOsSpecificTest().and(Approvals.NAMES::asMachineNameSpecificTest);
     ApprovalNamer namer = options.forFile().getNamer();
     String name = namer.getApprovedFile(".txt").getName();
     assertEquals("NamerFactoryForOptionsTest.testMachineSpecificTest.Mac_OS_X.lars-mbp-14.approved.txt", name);
+    // end-snippet
   }
   @Test
   void allHaveOptions()

approvaltests-tests/src/test/java/org/approvaltests/namer/NamerFactoryForOptionsTest.oldExampleForDocs.title.chapter.approved.txt

@@ -0,0 +1 @@
+data

approvaltests/docs/reference/Naming.md

@@ -0,0 +1,60 @@
+<a id="top"></a>
+
+# Naming
+
+<!-- toc -->
+## Contents
+
+  * [Paintables](#paintables)
+    * [Why](#why)
+  * [How To](#how-to)
+    * [create an animated gif](#create-an-animated-gif)<!-- endToc -->
+
+## Additional Naming Parameters
+
+By default an approval file will take the form of:  
+`classname.methodname.approved.txt`  
+
+There are a few cases where this is not sufficient:
+* You need more than one approval in a test method
+* You are using parameterized tests
+* You need different approvals per computer/OS/platform
+
+The way this is handled is through the naming factories. This will give you approval tests with the following:  
+`classname.methodname.additionalInformation.approved.txt`
+
+## How to do this
+
+### The old way
+There is a global namer factory that can be accessed with a try/catch. While this way works, it is not thread-safe
+and can cause trouble when running tests in parallel. Here is an example of how to do it:
+snippet: namer_factory_example
+
+This will result in a file named:
+`ClassName.methodName.firstString.secondString.approved.txt`
+
+### The new way
+With the addition of `Options` you can now set additional naming information in a thread-safe way. Here is an example of how to do that:
+
+snippet: additional_information_example
+
+This will result in a file named:
+`ClassName.methodName.firstString.secondString.approved.txt`
+
+#### Adding to an existing scenario
+If there is already an `Options` created, you can add to it using the `.and` keyword. Here is an example:
+
+snippet: options_and
+
+This will result in a file named: 
+`ClassName.methodName.OSName.machineName.approved.txt`
+
+## Parameterized Tests
+If you are using parameterized tests you will need to use additional names. See [How to use Approvals.verify in Parameterized Tests](../how_to/ParameterizedTest.md).
+
+## Only running on a specific machine
+
+Sometimes you have tests that cannot run on all of your machines. See [How to run tests only on specific machines](../how_to/MachineNameSpecificTest.md) 
+
+## Capturing approvals from CI
+If you are using special names per OS/platform your CI machines might not have a corresponding dev box. To handle this see [How to capture .received. files from CI](../how_to/CaptureFilesFromCI.md)

approvaltests/src/main/java/org/approvaltests/namer/NamerFactoryForOptions.java

@@ -25,4 +25,13 @@ public Options asMachineNameSpecificTest(Options options)
   {
     return options.forFile().withAdditionalInformation(SystemUtils.getComputerName());
   }
+  public Options withParameters(String... parameters) {
+    return withParameters(new Options(), parameters);
+  }
+  public Options withParameters(Options options, String... parameters) {
+    for (String parameter : parameters) {
+      options = options.forFile().withAdditionalInformation(parameter);
+    }
+    return options;
+  }
 }