Document deprecations in PrepareReleaseMojo and PerformReleaseMojo

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PerformReleaseMojo.java

@@ -86,14 +86,17 @@ public class PerformReleaseMojo extends AbstractScmReadReleaseMojo {
     private boolean localCheckout;
 
     /**
-     * Whether to use the default release profile (Maven 2 and 3) that adds sources and javadocs to the released
-     * artifact, if appropriate. If set to true, the release plugin sets the property "<code>performRelease</code>" to
-     * true, which activates the profile "<code>release-profile</code>" as inherited from
-     * <a href="/ref/3.8.5/maven-model-builder/super-pom.html">the super pom</a>.
-     * @deprecated The <code>release-profile</code> profile will be removed from future versions of the super POM
+     * Whether to use the default {@code release-profile} from the Maven super POM,
+     * which adds sources and javadocs to the released artifacts when appropriate.
+     *
+     * @deprecated The {@code release-profile} is being removed from future versions
+     *             of the Maven super POM. Projects that require sources or javadocs
+     *             to be attached during a release should configure their own
+     *             explicit build or release profiles instead of relying on this
+     *             implicit profile.
      */
-    @Parameter(defaultValue = "false", property = "useReleaseProfile")
     @Deprecated
+    @Parameter(defaultValue = "false", property = "useReleaseProfile")
     private boolean useReleaseProfile;
 
     /**

maven-release-plugin/src/main/java/org/apache/maven/plugins/release/PrepareReleaseMojo.java

@@ -62,7 +62,10 @@ public class PrepareReleaseMojo extends AbstractScmReadWriteReleaseMojo {
     private boolean resume;
 
     /**
-     * @deprecated Please use release:prepare-with-pom instead.
+     * Controls whether the plugin should generate release POMs during the
+     * prepare phase.
+     *
+     * @deprecated Use the {@code release:prepare-with-pom} goal instead.
      */
     @Deprecated
     @Parameter(defaultValue = "false", property = "generateReleasePoms")