Improve ByteBuddyElementMatchers javadoc

DataDog · Aug 1, 2018 · bb2126b · bb2126b
1 parent 2bfb7b9
commit bb2126b
Showing 1 changed file with 13 additions and 2 deletions.
diff --git a/...ent/agent-tooling/src/main/java/datadog/trace/agent/tooling/ByteBuddyElementMatchers.java b/...ent/agent-tooling/src/main/java/datadog/trace/agent/tooling/ByteBuddyElementMatchers.java
@@ -49,8 +49,19 @@ public static <T extends TypeDescription> ElementMatcher.Junction<T> safeHasGene
   }
 
   /**
-   * An element matcher that matches a super type. Exceptions during matching process are logged and
-   * ignored.
+   * An element matcher that matches a super type. This is different from {@link
+   * net.bytebuddy.matcher.HasSuperTypeMatcher} in the following way:
+   *
+   * <ul>
+   *   <li>Exceptions are logged
+   *   <li>When exception happens the rest of the inheritance subtree is discarded (since ByteBuddy
+   *       cannot load/parse type information for it) but search in other subtrees continues
+   * </ul>
+   *
+   * <p>This is useful because this allows us to see when matcher's check is not complete (i.e. part
+   * of it fails), at the same time it makes best effort instead of failing quickly (like {@code
+   * failSafe(hasSuperType(...))} does) which means the code is more resilient to classpath
+   * inconsistencies
    *
    * @param <T> The type of the matched entity.
    * @see net.bytebuddy.matcher.HasSuperTypeMatcher