diff --git a/asm-commons/src/main/java/org/objectweb/asm/commons/ClassRemapper.java b/asm-commons/src/main/java/org/objectweb/asm/commons/ClassRemapper.java
index a7f34ecf52e0bc0497426e20dfe787fcea6f1611..4860b827109bfc70a7093781de66f90213eea216 100644
--- a/asm-commons/src/main/java/org/objectweb/asm/commons/ClassRemapper.java
+++ b/asm-commons/src/main/java/org/objectweb/asm/commons/ClassRemapper.java
@@ -41,6 +41,20 @@ import org.objectweb.asm.TypePath;
 /**
  * A {@link ClassVisitor} that remaps types with a {@link Remapper}.
  *
+ * <p><i>This visitor has several limitations</i>. A non-exhaustive list is the following:
+ *
+ * <ul>
+ *   <li>it cannot remap type names in dynamically computed strings (remapping of type names in
+ *       static values is supported).
+ *   <li>it cannot remap values derived from type names at compile time, such as
+ *       <ul>
+ *         <li>type name hashcodes used by some Java compilers to implement the string switch
+ *             statement.
+ *         <li>some compound strings used by some Java compilers to implement lambda
+ *             deserialization.
+ *       </ul>
+ * </ul>
+ *
  * @author Eugene Kuleshov
  */
 public class ClassRemapper extends ClassVisitor {