#287: Add missing javadoc comments for the API module

api/src/main/java/org/itsallcode/openfasttrace/api/core/DeepCoverageStatus.java

@@ -24,26 +24,28 @@
 
 /**
  * This enumeration represents the different kinds of deep coverage.
- * 
- * <ul>
- * <li><code>COVERED</code> - this item and all its children are covered
- * correctly</li>
- * <li><code>UNCOVERED</code> - this item or at least one of its children are
- * not covered correctly</li>
- * <li><code>CYCLE</code> - this item is part of a link cycle, which means real
- * coverage cannot be evaluated</li>
- * </ul>
  */
 public enum DeepCoverageStatus
 {
-    COVERED(0), UNCOVERED(1), CYCLE(2);
+    /**
+     * This item and all its children are covered correctly.
+     */
+    COVERED(0),
+    /**
+     * This item or at least one of its children are not covered correctly
+     */
+    UNCOVERED(1),
+    /**
+     * This item is part of a link cycle, which means real coverage cannot be
+     * evaluated
+     */
+    CYCLE(2);
 
     private final int badness;
 
-    DeepCoverageStatus(final int badness)
+    private DeepCoverageStatus(final int badness)
     {
         this.badness = badness;
-
     }
 
     /**

api/src/main/java/org/itsallcode/openfasttrace/api/core/ItemStatus.java

@@ -22,10 +22,37 @@
  * #L%
  */
 
+/**
+ * This enumeration represents the different statuses of an item.
+ */
 public enum ItemStatus
 {
-    APPROVED, PROPOSED, DRAFT, REJECTED;
+    /**
+     * The item is approved.
+     */
+    APPROVED,
+    /**
+     * The item is proposed.
+     */
+    PROPOSED,
+    /**
+     * The item is a draft.
+     */
+    DRAFT,
+    /**
+     * The item is rejected.
+     */
+    REJECTED;
 
+    /**
+     * Parses the given text and return the matching {@link ItemStatus}.
+     * 
+     * @param text
+     *            the text to parse, e.g. {@code "APPROVED"}.
+     * @return the matching {@link ItemStatus}.
+     * @throws IllegalArgumentException
+     *             in case no matching {@link ItemStatus} is found.
+     */
     public static ItemStatus parseString(final String text)
     {
         for (final ItemStatus value : values())

api/src/main/java/org/itsallcode/openfasttrace/api/core/LinkStatus.java

@@ -22,22 +22,65 @@
  * #L%
  */
 
+/**
+ * This enumeration represents the different statuses of a coverage link between
+ * two items.
+ */
 public enum LinkStatus
 {
-    // Outgoing coverage link status
-    COVERS(" ", "covers"), PREDATED(">", "predated"), OUTDATED("<", "outdated"), AMBIGUOUS("?",
-            "ambiguous"), UNWANTED("+", "unwanted"), ORPHANED("/", "orphaned"), //
-    // Incoming coverage link status
-    COVERED_SHALLOW(" ", "covered shallow"), COVERED_UNWANTED("+",
-            "unwanted coverage"), COVERED_PREDATED(">",
-                    "predated coverage"), COVERED_OUTDATED("<", "outdated coverage"), //
-    // Duplicate link status
+    /**
+     * Outgoing coverage link status: item 1 covers item 2.
+     */
+    COVERS(" ", "covers"),
+    /**
+     * Outgoing coverage link status: item 1 covers a newer revision of item 2.
+     */
+    PREDATED(">", "predated"),
+    /**
+     * Outgoing coverage link status: item 1 covers an older revision of item 2.
+     */
+    OUTDATED("<", "outdated"),
+    /**
+     * Outgoing coverage link status: two items with the same id are covered by
+     * another item.
+     */
+    AMBIGUOUS("?", "ambiguous"),
+    /**
+     * Outgoing coverage link status: an item covers another item that does not
+     * require coverage.
+     */
+    UNWANTED("+", "unwanted"),
+    /** Outgoing coverage link status: an item covers a non-existing item. */
+    ORPHANED("/", "orphaned"),
+
+    /**
+     * Incoming coverage link status: an item is directly covered by another
+     * item.
+     */
+    COVERED_SHALLOW(" ", "covered shallow"),
+    /**
+     * Incoming coverage link status: an item is covered by another item
+     * although it does not require coverage.
+     */
+    COVERED_UNWANTED("+", "unwanted coverage"),
+    /**
+     * Incoming coverage link status: an item is covered by another item that
+     * specifies a newer revision.
+     */
+    COVERED_PREDATED(">", "predated coverage"),
+    /**
+     * Incoming coverage link status: an item is covered by another item that
+     * specifies an older revision.
+     */
+    COVERED_OUTDATED("<", "outdated coverage"),
+
+    /** Duplicate link status: two items have the same ID. */
     DUPLICATE("?", "duplicate");
 
     private final String shortTag;
     private final String text;
 
-    LinkStatus(final String shortTag, final String text)
+    private LinkStatus(final String shortTag, final String text)
     {
         this.shortTag = shortTag;
         this.text = text;

api/src/main/java/org/itsallcode/openfasttrace/api/core/LinkedSpecificationItem.java

@@ -43,8 +43,9 @@ public class LinkedSpecificationItem
     /**
      * Create a new instance of class {@link LinkedSpecificationItem}.
      *
-     * @param item the actual specification item that is at the center of the
-     *             links
+     * @param item
+     *            the actual specification item that is at the center of the
+     *            links
      */
     public LinkedSpecificationItem(final SpecificationItem item)
     {
@@ -148,8 +149,10 @@ public SpecificationItem getItem()
     /**
      * Add a link to another item with a status.
      *
-     * @param item   the item to be linked to
-     * @param status the link status
+     * @param item
+     *            the item to be linked to
+     * @param status
+     *            the link status
      */
     public void addLinkToItemWithStatus(final LinkedSpecificationItem item, final LinkStatus status)
     {
@@ -211,7 +214,8 @@ public Map<LinkStatus, List<LinkedSpecificationItem>> getLinks()
     /**
      * Get all links to the item by item status.
      *
-     * @param status link status
+     * @param status
+     *            link status
      * @return the covered items
      */
     public List<LinkedSpecificationItem> getLinksByStatus(final LinkStatus status)
@@ -303,7 +307,8 @@ public List<String> getUncoveredArtifactTypes()
     }
 
     /**
-     * Get a list of all artifact types for which required coverage is missing only considering approved items.
+     * Get a list of all artifact types for which required coverage is missing
+     * only considering approved items.
      *
      * @return list of uncovered artifact types.
      */
@@ -326,7 +331,8 @@ public boolean isCoveredShallow()
     }
 
     /**
-     * @return <code>true</code> if all needed attribute types are covered by approved items
+     * @return <code>true</code> if all needed attribute types are covered by
+     *         approved items
      */
     public boolean isCoveredShallowWithApprovedItems()
     {
@@ -336,7 +342,7 @@ public boolean isCoveredShallowWithApprovedItems()
     /**
      * Check if this item and all items providing coverage for it are covered.
      *
-     * @return covered, uncovered or ring.
+     * @return covered, uncovered or cycle.
      */
     // [impl->dsn~tracing.deep-coverage~1]
     public DeepCoverageStatus getDeepCoverageStatus()
@@ -345,6 +351,12 @@ public DeepCoverageStatus getDeepCoverageStatus()
                 DeepCoverageStatus.COVERED, false);
     }
 
+    /**
+     * Check if this item and all items providing coverage for it are covered,
+     * conly considering items with status {@link ItemStatus#APPROVED}.
+     *
+     * @return covered, uncovered or cycle.
+     */
     public DeepCoverageStatus getDeepCoverageStatusOnlyAcceptApprovedItems()
     {
         return getDeepCoverageStatusEndRecursionStartingAt(this.getId(),
@@ -389,9 +401,9 @@ private DeepCoverageStatus getDeepCoverageStatusEndRecursionStartingAt(
     private DeepCoverageStatus adjustDeepCoverageStatusIfApprovedRequired(final boolean onlyAcceptApprovedItemStatus,
             final DeepCoverageStatus deepCoveredStatus)
     {
-        return (onlyAcceptApprovedItemStatus && deepCoveredStatus == DeepCoverageStatus.COVERED && !isApproved()) ?
-                DeepCoverageStatus.UNCOVERED :
-                deepCoveredStatus;
+        return (onlyAcceptApprovedItemStatus && deepCoveredStatus == DeepCoverageStatus.COVERED && !isApproved())
+                ? DeepCoverageStatus.UNCOVERED
+                : deepCoveredStatus;
     }
 
     private List<LinkedSpecificationItem> getIncomingItems()
@@ -424,8 +436,8 @@ public boolean isDefect()
     {
         return hasDuplicates() //
                 || (getStatus() != ItemStatus.REJECTED) //
-                && (hasBadLinks()
-                || (getDeepCoverageStatus() != DeepCoverageStatus.COVERED));
+                        && (hasBadLinks()
+                                || (getDeepCoverageStatus() != DeepCoverageStatus.COVERED));
     }
 
     /**

api/src/main/java/org/itsallcode/openfasttrace/api/core/Location.java

@@ -24,9 +24,14 @@
 
 import javax.annotation.processing.Generated;
 
+/**
+ * The location of a coverage item.
+ */
 public final class Location
 {
+    /** Value indicating an unknown line. */
     public static final int NO_LINE = -1;
+    /** Value indicating an unknown column. */
     public static final int NO_COLUMN = -1;
     private final String path;
     private final int line;
@@ -197,6 +202,10 @@ public static Builder builder()
         return new Builder();
     }
 
+    /**
+     * A builder for {@link Location}. Use {@link Location#builder()} to create
+     * a new builder and call {@link #build()} to build a {@link Location}.
+     */
     public static class Builder
     {
         private String path;

api/src/main/java/org/itsallcode/openfasttrace/api/core/Newline.java

@@ -24,16 +24,23 @@
 
 import java.util.regex.Pattern;
 
-
+/**
+ * This enumeration represents the different types of newline.
+ */
 public enum Newline
 {
-    UNIX("\n"), WINDOWS("\r\n"), OLDMAC("\r");
+    /** Newline character used under Unix. */
+    UNIX("\n"),
+    /** Newline characters used under windows. */
+    WINDOWS("\r\n"),
+    /** Newline character used on old macs. */
+    OLDMAC("\r");
 
     private static final String ANY_NEWLINE_REG_EX = "\\r\\n|\\r|\\n";
     private static final Pattern ANY_NEWLINE_PATTERN = Pattern.compile(ANY_NEWLINE_REG_EX);
     private final String representation;
 
-    Newline(final String representation)
+    private Newline(final String representation)
     {
         this.representation = representation;
     }

api/src/main/java/org/itsallcode/openfasttrace/api/core/SpecificationItem.java

@@ -28,6 +28,10 @@
 
 import javax.annotation.processing.Generated;
 
+/**
+ * A specification item that requires coverage from other items and provides
+ * coverage for other items.
+ */
 // [impl->dsn~specification-item~3]
 public class SpecificationItem
 {
@@ -85,8 +89,8 @@ public String getArtifactType()
      * 
      * <p>
      * Not to be mixed up with the
-     * {@link org.itsallcode.openfasttrace.api.core.SpecificationItem#getTitle()} of
-     * the specification item
+     * {@link org.itsallcode.openfasttrace.api.core.SpecificationItem#getTitle()}
+     * of the specification item
      * </p>
      * 
      * @return name part of the specification item ID
@@ -530,6 +534,13 @@ public Builder comment(final String comment)
             return this;
         }
 
+        /**
+         * Set the status
+         * 
+         * @param status
+         *            the status
+         * @return this builder instance
+         */
         public Builder status(final ItemStatus status)
         {
             this.status = status;

api/src/main/java/org/itsallcode/openfasttrace/api/core/SpecificationItemId.java

@@ -39,14 +39,21 @@ public class SpecificationItemId implements Comparable<SpecificationItemId>
 {
     private static final Logger LOG = Logger.getLogger(SpecificationItemId.class.getName());
 
+    /**
+     * Value for an unknown artifact type in case the type could not be
+     * determined for a legacy item ID.
+     */
     public static final String UNKNOWN_ARTIFACT_TYPE = "unknown";
-    public static final String ITEM_REVISION_PATTERN = "(\\d+)";
+    private static final String ITEM_REVISION_PATTERN = "(\\d+)";
+    /** Regexp pattern for item names. */
     public static final String ITEM_NAME_PATTERN = "(\\p{Alpha}[\\w-]*(?:\\.\\p{Alpha}[\\w-]*)*)";
     private static final String LEGACY_ID_NAME = "(\\p{Alpha}+)(?:~\\p{Alpha}+)?:"
             + ITEM_NAME_PATTERN;
+    /** Separator between artifact type and name in an item ID. */
     public static final String ARTIFACT_TYPE_SEPARATOR = "~";
+    /** Separator between name and revision in an item ID. */
     public static final String REVISION_SEPARATOR = "~";
-    public static final int REVISION_WILDCARD = Integer.MIN_VALUE;
+    static final int REVISION_WILDCARD = Integer.MIN_VALUE;
     // [impl->dsn~md.specification-item-id-format~2]
     private static final String ID = "(\\p{Alpha}+)" //
             + ARTIFACT_TYPE_SEPARATOR //
@@ -59,15 +66,17 @@ public class SpecificationItemId implements Comparable<SpecificationItemId>
     private static final int ARTIFACT_TYPE_MATCHING_GROUP = 1;
     private static final int NAME_MATCHING_GROUP = 2;
     private static final int REVISION_MATCHING_GROUP = 3;
+    /** Regexp pattern for item IDs: {@code <type>~<name>~<revision>} */
     public static final Pattern ID_PATTERN = Pattern.compile(ID);
-    public static final Pattern LEGACY_NAME_PATTERN = Pattern.compile(LEGACY_ID_NAME);
+    private static final Pattern LEGACY_NAME_PATTERN = Pattern.compile(LEGACY_ID_NAME);
+    /** Regexp pattern for legacy item IDs: {@code <name>, v<revision>}. */
     public static final Pattern LEGACY_ID_PATTERN = Pattern.compile(LEGACY_ID);
 
     private final String name;
     private final int revision;
     private final String artifactType;
 
-    protected SpecificationItemId(final String name, final String artifactType, final int revision)
+    private SpecificationItemId(final String name, final String artifactType, final int revision)
     {
         this.name = name;
         this.artifactType = artifactType;
@@ -174,6 +183,9 @@ public String toString()
         return builder.toString();
     }
 
+    /**
+     * @return a copy of this ID with a wildcard as revision.
+     */
     public SpecificationItemId toRevisionWildcard()
     {
         return new Builder().artifactType(this.artifactType).name(this.name).revisionWildcard()