Added explanatory Javadoc comments for relatedDependency behavior and purpose. Added logging whenever there is a collision adding to relatedDependency.

Former-commit-id: 99d3c9527541769e47008a9c919e4727bd2bf623

dependency-check-core/src/main/java/org/owasp/dependencycheck/dependency/Dependency.java

@@ -591,7 +591,8 @@ public class Dependency implements Serializable, Comparable<Dependency> {
     private Set<Dependency> relatedDependencies = new TreeSet<Dependency>();
 
     /**
-     * Get the value of relatedDependencies.
+     * Get the value of {@link #relatedDependencies}. This field is used to collect other dependencies which really
+     * represent the same dependency, and may be presented as one item in reports.
      *
      * @return the value of relatedDependencies
      */
@@ -650,18 +651,25 @@ public class Dependency implements Serializable, Comparable<Dependency> {
     }
 
     /**
-     * Adds a related dependency.
+     * Adds a related dependency. The internal collection is normally a {@link java.util.TreeSet}, which relies on
+     * {@link #compareTo(Dependency)}. A consequence of this is that if you attempt to add a dependency with the
+     * same file path (modulo character case) as one that is already in the collection, it won't get added.
      *
      * @param dependency a reference to the related dependency
      */
     public void addRelatedDependency(Dependency dependency) {
+        boolean debug = false;
         if (this == dependency) {
             LOGGER.warn("Attempted to add a circular reference - please post the log file to issue #172 here "
                     + "https://github.com/jeremylong/DependencyCheck/issues/172");
+            debug = true;
+        } else if (!relatedDependencies.add(dependency)) {
+            LOGGER.warn("Failed to add dependency, likely due to referencing the same file as another dependency in the set.");
+            debug = true;
+        }
+        if (debug) {
             LOGGER.debug("this: {}", this);
             LOGGER.debug("dependency: {}", dependency);
-        } else {
-            relatedDependencies.add(dependency);
         }
     }
 
@@ -698,7 +706,7 @@ public class Dependency implements Serializable, Comparable<Dependency> {
     }
 
     /**
-     * Implementation of the Comparable<Dependency> interface. The comparison is solely based on the file name.
+     * Implementation of the Comparable<Dependency> interface. The comparison is solely based on the file path.
      *
      * @param o a dependency to compare
      * @return an integer representing the natural ordering