diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/MojoDescriptor.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/MojoDescriptor.java
index f32fbe41159c..9d946b595715 100644
--- a/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/MojoDescriptor.java
+++ b/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/MojoDescriptor.java
@@ -88,8 +88,8 @@ public class MojoDescriptor
     private String executeLifecycle;
 
     /**
-     * Specify the version when the Mojo was deprecated to the API. Similar to Javadoc deprecated. This will trigger a
-     * warning when a user tries to configure a parameter marked as deprecated.
+     * Description with reason of Mojo deprecation. Similar to Javadoc {@code @deprecated}.
+     * This will trigger a warning when a user tries to use a Mojo marked as deprecated.
      */
     private String deprecated;
 
@@ -170,7 +170,7 @@ public void setLanguage( String language )
     }
 
     /**
-     * @return <code>true</code> if the Mojo is deprecated, <code>false</code> otherwise.
+     * @return Description with reason of a Mojo deprecation.
      */
     public String getDeprecated()
     {
@@ -178,7 +178,7 @@ public String getDeprecated()
     }
 
     /**
-     * @param deprecated <code>true</code> to deprecate the Mojo, <code>false</code> otherwise.
+     * @param deprecated Description with reason of a Mojo deprecation.
      */
     public void setDeprecated( String deprecated )
     {
diff --git a/maven-plugin-api/src/main/mdo/plugin.mdo b/maven-plugin-api/src/main/mdo/plugin.mdo
index ee80045dfef2..5156b0f7e228 100644
--- a/maven-plugin-api/src/main/mdo/plugin.mdo
+++ b/maven-plugin-api/src/main/mdo/plugin.mdo
@@ -289,10 +289,10 @@ under the License.
           <name>deprecated</name>
           <version>1.0.0</version>
           <type>String</type>
-          <description>
-            Specify the version when the Mojo was deprecated to the API. Similar to Javadoc deprecated. This will
-            trigger a warning when a user tries to configure a parameter marked as deprecated.
-          </description>
+          <description><![CDATA[
+            Description with the reason of Mojo deprecation. Similar to Javadoc <code>@deprecated</code>
+            This will trigger a warning when a user tries to use a Mojo marked as deprecated.
+          ]]></description>
         </field>
         <field>
           <name>configurator</name>
@@ -422,10 +422,10 @@ under the License.
           <name>deprecated</name>
           <version>1.0.0</version>
           <type>String</type>
-          <description>
-            Specify the version when the parameter was deprecated to the API. Similar to Javadoc deprecated.
+          <description><![CDATA[
+            Description with the reason of parameter deprecation. Similar to Javadoc <code>@deprecated</code>
             This will trigger a warning when a user tries to configure a parameter marked as deprecated.
-          </description>
+          ]]></description>
         </field>
       </fields>
     </class>