#287: Add javadoc comments

core/src/main/java/org/itsallcode/openfasttrace/core/LinkedItemIndex.java

@@ -29,6 +29,10 @@
 
 import org.itsallcode.openfasttrace.api.core.*;
 
+/**
+ * An idex for {@link LinkedSpecificationItem} that allows retrieving items by
+ * {@link SpecificationItemId}, optionally ignoring the revision.
+ */
 public class LinkedItemIndex
 {
     private final Map<SpecificationItemId, LinkedSpecificationItem> idIndex;
@@ -41,6 +45,13 @@ private LinkedItemIndex(final Map<SpecificationItemId, LinkedSpecificationItem>
         this.idIndexIgnoringVersion = idIndexIgnoringVersion;
     }
 
+    /**
+     * Create a new index containing the given items.
+     * 
+     * @param items
+     *            the items to add to the new index.
+     * @return a new index.
+     */
     public static LinkedItemIndex create(final List<SpecificationItem> items)
     {
         return createFromWrappedItems(wrapItems(items));
@@ -51,6 +62,13 @@ private static List<LinkedSpecificationItem> wrapItems(final List<SpecificationI
         return items.stream().map(LinkedSpecificationItem::new).collect(Collectors.toList());
     }
 
+    /**
+     * Create a new index containing the given wrapped items.
+     * 
+     * @param wrappedItems
+     *            the items to add to the new index.
+     * @return a new index.
+     */
     public static LinkedItemIndex createFromWrappedItems(
             final List<LinkedSpecificationItem> wrappedItems)
     {
@@ -84,21 +102,41 @@ private static LinkedSpecificationItem handleDuplicates(final LinkedSpecificatio
         return item1;
     }
 
+    /**
+     * @return the total number of items in this index.
+     */
     public int size()
     {
         return this.idIndex.size();
     }
 
+    /**
+     * Get an item by id.
+     * 
+     * @param id
+     *            the item id.
+     * @return the item with the given id or {@code null} if no item exists.
+     */
     public LinkedSpecificationItem getById(final SpecificationItemId id)
     {
         return this.idIndex.get(id);
     }
 
+    /**
+     * @return the number of IDs ignoring the version.
+     */
     public int sizeIgnoringVersion()
     {
         return this.idIndexIgnoringVersion.size();
     }
 
+    /**
+     * Get all items for the given ID, ignoring the version.
+     * 
+     * @param id
+     *            the item id.
+     * @return the item with the given id or {@code null} if no item exists.
+     */
     public List<LinkedSpecificationItem> getByIdIgnoringVersion(final SpecificationItemId id)
     {
         final List<LinkedSpecificationItem> items = this.idIndexIgnoringVersion

core/src/main/java/org/itsallcode/openfasttrace/core/Linker.java

@@ -30,6 +30,9 @@
 
 import org.itsallcode.openfasttrace.api.core.*;
 
+/**
+ * Links a given list of {@link SpecificationItem}s and returns {@link LinkedSpecificationItem}s.
+ */
 public class Linker
 {
     private final List<LinkedSpecificationItem> linkedItems;

core/src/main/java/org/itsallcode/openfasttrace/core/OftRunner.java

@@ -31,10 +31,14 @@
 import org.itsallcode.openfasttrace.api.core.Trace;
 import org.itsallcode.openfasttrace.api.importer.ImportSettings;
 
+/**
+ * Provides convenient methods for importing, tracing and reporting.
+ */
 public class OftRunner implements Oft
 {
     private final ServiceFactory serviceFactory;
 
+    /** Create a new instance. */
     public OftRunner()
     {
         this(new ServiceFactory());

core/src/main/java/org/itsallcode/openfasttrace/core/Tracer.java

@@ -28,8 +28,19 @@
 import org.itsallcode.openfasttrace.api.core.LinkedSpecificationItem;
 import org.itsallcode.openfasttrace.api.core.Trace;
 
+/**
+ * Traces a given list of {@link LinkedSpecificationItem}s and returns a
+ * {@link Trace} as input for reporters.
+ */
 public class Tracer
 {
+    /**
+     * Traces the given items.
+     * 
+     * @param items
+     *            the items to trace.
+     * @return the result {@link Trace}.
+     */
     public Trace trace(final List<LinkedSpecificationItem> items)
     {
         final Trace.Builder builder = Trace.builder();

core/src/main/java/org/itsallcode/openfasttrace/core/cli/commands/AbstractCommand.java

@@ -41,16 +41,24 @@
  */
 public abstract class AbstractCommand implements Performable
 {
+    /** The command line arguments given by the user. */
     protected CliArguments arguments;
+    /** The OFT instance for executing commands. */
     protected final Oft oft;
 
+    /**
+     * Creates a new instance.
+     * 
+     * @param arguments
+     *            the command line arguments.
+     */
     protected AbstractCommand(final CliArguments arguments)
     {
         this.arguments = arguments;
         this.oft = Oft.create();
     }
 
-    protected List<Path> toPaths(final List<String> inputs)
+    private List<Path> toPaths(final List<String> inputs)
     {
         final List<Path> inputsAsPaths = new ArrayList<>();
         for (final String input : inputs)
@@ -60,7 +68,7 @@ protected List<Path> toPaths(final List<String> inputs)
         return inputsAsPaths;
     }
 
-    protected FilterSettings createFilterSettingsFromArguments()
+    private FilterSettings createFilterSettingsFromArguments()
     {
         final FilterSettings.Builder builder = new FilterSettings.Builder();
         setAttributeTypeFilter(builder);
@@ -95,12 +103,17 @@ private void setTagFilter(final FilterSettings.Builder builder)
         }
     }
 
+    /**
+     * Import items using filter settings from command line arguments.
+     * 
+     * @return the imported items.
+     */
     protected List<SpecificationItem> importItems()
     {
-        final ImportSettings importSettings = ImportSettings //
-                .builder() //
-                .addInputs(this.toPaths(this.arguments.getInputs())) //
-                .filter(createFilterSettingsFromArguments()) //
+        final ImportSettings importSettings = ImportSettings
+                .builder()
+                .addInputs(this.toPaths(this.arguments.getInputs()))
+                .filter(createFilterSettingsFromArguments())
                 .build();
         return this.oft.importItems(importSettings);
     }

core/src/main/java/org/itsallcode/openfasttrace/core/importer/ImporterServiceImpl.java

@@ -27,6 +27,11 @@
 import org.itsallcode.openfasttrace.api.importer.*;
 import org.itsallcode.openfasttrace.api.importer.input.InputFile;
 
+/**
+ * An implementation of the {@link ImporterService} interface. This service
+ * provides convenient methods for importing {@link SpecificationItem}s that
+ * automatically use the correct {@link Importer} based on the filename.
+ */
 public class ImporterServiceImpl implements ImporterService
 {
     private final ImporterFactoryLoader factoryLoader;

exporter/common/src/main/java/org/itsallcode/openfasttrace/exporter/common/DelegatingXMLStreamWriter.java

@@ -26,7 +26,7 @@
 import javax.xml.stream.XMLStreamException;
 import javax.xml.stream.XMLStreamWriter;
 
-public class DelegatingXMLStreamWriter implements XMLStreamWriter
+class DelegatingXMLStreamWriter implements XMLStreamWriter
 {
     private final XMLStreamWriter writer;
 

exporter/common/src/main/java/org/itsallcode/openfasttrace/exporter/common/IndentingXMLStreamWriter.java

@@ -27,6 +27,10 @@
 import java.util.Deque;
 import java.util.LinkedList;
 
+/**
+ * An {@link XMLStreamWriter} that wraps another {@link XMLStreamWriter} and
+ * indents the output.
+ */
 public class IndentingXMLStreamWriter extends DelegatingXMLStreamWriter implements AutoCloseable
 {
     private enum State
@@ -42,6 +46,12 @@ private enum State
 
     private int depth = 0;
 
+    /**
+     * Create an new instance wrapping a delegate.
+     * 
+     * @param writer
+     *            the delegate writer.
+     */
     public IndentingXMLStreamWriter(XMLStreamWriter writer)
     {
         super(writer);

exporter/specobject/src/main/java/org/itsallcode/openfasttrace/exporter/specobject/SpecobjectExporterFactory.java

@@ -42,9 +42,10 @@
  */
 public class SpecobjectExporterFactory extends ExporterFactory
 {
-    public static final String SUPPORTED_FORMAT = "specobject";
+    private static final String SUPPORTED_FORMAT = "specobject";
     private final XMLOutputFactory xmlOutputFactory;
 
+    /** Creates a new instance. */
     public SpecobjectExporterFactory()
     {
         super(SUPPORTED_FORMAT);

importer/markdown/src/main/java/org/itsallcode/openfasttrace/importer/markdown/MarkdownForwardingSpecificationItem.java

@@ -34,8 +34,8 @@
  */
 public class MarkdownForwardingSpecificationItem
 {
-    public static final String ORIGINAL_MARKER = ":";
-    public static final String FORWARD_MARKER = "-->";
+    static final String ORIGINAL_MARKER = ":";
+    static final String FORWARD_MARKER = "-->";
     private final String skippedArtifactType;
     private final SpecificationItemId originalId;
     private final SpecificationItemId skippedId;

importer/markdown/src/main/java/org/itsallcode/openfasttrace/importer/markdown/MarkdownImporterFactory.java

@@ -30,6 +30,7 @@
  */
 public class MarkdownImporterFactory extends RegexMatchingImporterFactory
 {
+    /** Creates a new instance. */
     public MarkdownImporterFactory()
     {
         super("(?i).*\\.markdown", "(?i).*\\.md");

importer/markdown/src/main/java/org/itsallcode/openfasttrace/importer/markdown/TransitionAction.java

@@ -24,7 +24,7 @@
 
 
 @FunctionalInterface
-public interface TransitionAction
+interface TransitionAction
 {
     void transit();
 }

importer/tag/src/main/java/org/itsallcode/openfasttrace/importer/tag/ChecksumCalculator.java

@@ -25,11 +25,10 @@
 import java.nio.charset.StandardCharsets;
 import java.util.zip.CRC32;
 
-public class ChecksumCalculator
+class ChecksumCalculator
 {
     private ChecksumCalculator()
     {
-
     }
 
     public static long calculateCrc32(final String value)

importer/tag/src/main/java/org/itsallcode/openfasttrace/importer/tag/LineReader.java

@@ -28,7 +28,7 @@
 import org.itsallcode.openfasttrace.api.importer.ImporterException;
 import org.itsallcode.openfasttrace.api.importer.input.InputFile;
 
-public class LineReader
+class LineReader
 {
     private final InputFile file;
 

importer/tag/src/main/java/org/itsallcode/openfasttrace/importer/tag/TagImporterFactory.java

@@ -73,7 +73,7 @@ private boolean supportsConfiguredFile(final InputFile path)
         return findConfig(path).isPresent();
     }
 
-    public boolean supportsDefaultFile(final InputFile file)
+    boolean supportsDefaultFile(final InputFile file)
     {
         final String path = file.getPath();
         final int lastDotPosition = path.lastIndexOf(".");

importer/zip/src/main/java/org/itsallcode/openfasttrace/importer/zip/ZipFileImporterFactory.java

@@ -34,6 +34,7 @@
  */
 public class ZipFileImporterFactory extends RegexMatchingImporterFactory
 {
+    /** Creates a new instance. */
     public ZipFileImporterFactory()
     {
         super("(?i).*\\.(zip)");

reporter/html/src/main/java/org/itsallcode/openfasttrace/report/html/view/AbstractViewFactory.java

@@ -24,6 +24,10 @@
 
 import java.io.PrintStream;
 
+/**
+ * Factory that creates OFT view (e.g. for reports) and provides an output
+ * stream.
+ */
 public abstract class AbstractViewFactory implements ViewFactory
 {
     protected final PrintStream outputStream;