diff --git a/docs/en/reference/index.rst b/docs/en/reference/index.rst
index e17eca8f..f9646a6d 100644
--- a/docs/en/reference/index.rst
+++ b/docs/en/reference/index.rst
@@ -149,10 +149,12 @@ your mapped PHP classes.
         public function getAllMetadata();
         public function getMetadataFor($className);
         public function hasMetadataFor($className);
-        public function setMetadataFor($className, $class);
+        public function setMetadataFor($className, $class); // Deprecated
         public function isTransient($className);
     }
 
+The method ``setMetadataFor()`` is deprecated and should not be used.
+
 Mapping Driver
 ==============
 
diff --git a/src/Mapping/AbstractClassMetadataFactory.php b/src/Mapping/AbstractClassMetadataFactory.php
index b2f0573d..575c0f01 100644
--- a/src/Mapping/AbstractClassMetadataFactory.php
+++ b/src/Mapping/AbstractClassMetadataFactory.php
@@ -232,7 +232,7 @@ public function hasMetadataFor(string $className): bool
     /**
      * Sets the metadata descriptor for a specific class.
      *
-     * NOTE: This is only useful in very special cases, like when generating proxy classes.
+     * @deprecated Since 4.2, use a custom ClassMetadataFactory implementation if you need to set metadata manually.
      *
      * @phpstan-param class-string $className
      * @phpstan-param CMTemplate $class
diff --git a/src/Mapping/ClassMetadataFactory.php b/src/Mapping/ClassMetadataFactory.php
index 68e4595b..6b3c2ae8 100644
--- a/src/Mapping/ClassMetadataFactory.php
+++ b/src/Mapping/ClassMetadataFactory.php
@@ -41,6 +41,8 @@ public function hasMetadataFor(string $className): bool;
     /**
      * Sets the metadata descriptor for a specific class.
      *
+     * @deprecated Since 4.2, use a custom ClassMetadataFactory implementation if you need to set metadata manually.
+     *
      * @param class-string $className
      * @phpstan-param T $class
      */