#338: Fixed review findings. Improved user guide.

api/src/main/java/org/itsallcode/openfasttrace/api/ReportSettings.java

@@ -24,7 +24,7 @@ private ReportSettings(final Builder builder)
         this.showOrigin = builder.showOrigin;
         this.outputFormat = builder.outputFormat;
         this.newline = builder.newline;
-        this.colorScheme = builder.colorScheme;
+        this.colorScheme = Objects.requireNonNull(builder.colorScheme);
     }
 
     /**
@@ -178,7 +178,7 @@ public Builder newline(final Newline newline)
         /**
          * Set the desired color scheme
          *
-         * @param colorScheme set to true to get a colored report
+         * @param colorScheme color scheme to use
          * @return <code>this</code> for fluent programming
          */
         public Builder colorScheme(final ColorScheme colorScheme) {

core/src/test/java/org/itsallcode/openfasttrace/core/cli/TestCliArguments.java

@@ -259,14 +259,6 @@ void testColorSchemeDefaultsToColor()
         assertThat(this.arguments.getColorScheme(), is(ColorScheme.COLOR));
     }
 
-
-    @Test
-    void testSetOutputColorScheme()
-    {
-        this.arguments.setColorScheme(ColorScheme.MONOCHROME);
-        assertThat(this.arguments.getColorScheme(), is(ColorScheme.MONOCHROME));
-    }
-
     @Test
     void testSetOutputFileOverridesColorSchemeSetting()
     {

doc/spec/design.md

@@ -380,6 +380,7 @@ The plain text report uses ANSI escape sequences to modify the font style of the
 Covers:
 
 * `req~colored-plain-text-report~1`
+* `req~monochrome-plain-text-report-with-font-style~1`
 
 Needs: impl, utest
 

doc/spec/system_requirements.md

@@ -121,7 +121,7 @@ A tracing report is a representation of the results of the requirement tracing O
 
 #### Console Reports
 
-#### Plain Text Report
+##### Plain Text Report
 `feat~plain-text-report~1`
 
 OFT produces a tracing report in plain text.
@@ -531,30 +531,28 @@ Covers:
 Needs: dsn
 
 ##### Monochrome Plain Text Report With Font Style
-
-`List.of`
+`req~monochrome-plain-text-report-with-font-style~1`
 
 The plain text report supports different font styles to visually separate report elements.
 
 Rationale:
 
-This make the report easier to read and works for people who are colorblind.
+This makes the report easier to read and works for people who are colorblind.
 
 Covers:
 
 * [feat~plain-text-report~1](#plain-text-report)
 
 Needs: dsn
 
-
 ##### Colored Plain Text Report
 `req~colored-plain-text-report~1`
 
 The plain text report supports color to visually separate report elements.
 
 Rationale:
 
-This make the report easier to read.
+This makes the report easier to read.
 
 Covers:
 

doc/user_guide.md

@@ -526,6 +526,9 @@ Here is an example of a tag embedded into a Java comment:
 
 ```java
 // [impl->dsn~validate-authentication-request~1]
+private validate(final AuthenticationRequest request){
+    // ...
+}
 ```
 
 When using UML models as design document files like UML models it is useful to add needed coverage as well. To do this, you can use the following format:
@@ -536,8 +539,9 @@ When using UML models as design document files like UML models it is useful to a
 
 Example:
 
-```plantuml
+```
 ' [dsn->req~1password-login~1>>impl,test]
+user -> system : login(token: OAuthToken)
 ```
 
 The Tag Importer recognizes the supported format by the file extension. The following list shows the standard set of
@@ -627,6 +631,8 @@ The first pair shows how many of the incoming good links this requirement has (t
 
 Consequently, the next pair informs you how many (one) of the overall (one) outgoing links are good.
 
+Please note that OFT cannot predict the exact number of required incoming links, because often we are talking about one-to-many relations. So OFT does not try to. The checkmark and crossmark in the square brackets are only a quick indicator of if the existing links are okay. This goes so far that in case of zero links, no mark is displayed at all.
+
 >  ok [ in:  2 /  2 ✔ | **out:  1 /  1 ✔** ] dsn~cli.tracing.default-format~1 (impl, utest)
 
 The [Specification Item ID](#specification-item-id) in the middle is the unique technical ID of this requirement.
@@ -635,23 +641,21 @@ The [Specification Item ID](#specification-item-id) in the middle is the unique
 
 In the brackets you find, which artifact types this item expects as coverage. If the type is covered correctly, you see just the name there. 
 
->  ok [ in:  2 /  2 ✔ | out:  1 /  1 ✔ ] dsn~cli.tracing.default-format~1 (**impl, utest***)
+>  ok [ in:  2 /  2 ✔ | out:  1 /  1 ✔ ] dsn~cli.tracing.default-format~1 (**impl, utest**)
 
 If it is not covered, the name is lead in by a minus:
 
->  **not ok** ...  (**-impl**, utest)
-
-Please also note that in this case the number of incoming links changed and that a cross-mark indicates that at least one 
-
+>  **not ok** …  (**-impl**, utest)
+ 
 If an artifact type provides coverage that is not requested, you find this indicated with a plus in front.
 
-> not ok - 0/2>0>0/1 - `dsn~cli.tracing.default-format~1` (impl, **+itest**, utest)
+> **not ok** … (impl, **+itest**, utest)
 
-If there were any other spec objects defined with the same id, you would see the following at the end of the summary line:
+If there were any other specification objects defined with the same ID, you would see the following at the end of the summary line:
 
 > [has 3 duplicates]
 
-Everything after that line is details of the requirement. Indented text indicates this. The first part of the details is the description.
+Everything after that line are details of the requirement. Indented text indicates this. The first part of the details is the description.
 
     The CLI uses plain text as requirement tracing report format if none is given as a parameter.
 

reporter/plaintext/src/main/java/org/itsallcode/openfasttrace/report/plaintext/AnsiSequence.java

@@ -9,7 +9,7 @@ enum AnsiSequence {
     /** Reset all font effects */
     RESET(0),
     /** Bold font */
-    BOLD (1),
+    BOLD(1),
     /** Italic font */
     ITALIC(3),
     /** Underlined */

reporter/plaintext/src/main/java/org/itsallcode/openfasttrace/report/plaintext/TextFormatter.java

@@ -12,7 +12,7 @@ interface TextFormatter {
     public String formatOk(final String text);
 
     /**
-     * Format a text span that represents a good result.
+     * Format a text span that represents a bad result.
      *
      * @param text text span to be formatted
      * @return formatted text

reporter/plaintext/src/test/java/org/itsallcode/openfasttrace/report/plaintext/TestTextFormatterFactory.java

@@ -7,6 +7,7 @@
 import static org.hamcrest.core.IsInstanceOf.instanceOf;
 import static org.itsallcode.openfasttrace.api.ColorScheme.*;
 import static org.itsallcode.openfasttrace.report.plaintext.TextFormatterFactory.createFormatter;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 class TestTextFormatterFactory {
     @Test
@@ -23,4 +24,9 @@ void testCreateMonochromeTextFormatter() {
     void testCreateConsoleColorFormatter() {
         assertThat(createFormatter(COLOR), instanceOf(ConsoleColorFormatter.class));
     }
+
+    @Test
+    void testCreateDefaultFormatter() {
+        assertThat(createFormatter(null), instanceOf(NullTextFormatter.class));
+    }
 }