Improve documentation of parameters

src/main/java/org/apache/maven/plugins/scmpublish/AbstractScmPublishMojo.java

@@ -66,10 +66,13 @@
 public abstract class AbstractScmPublishMojo extends AbstractMojo {
     // CHECKSTYLE_OFF: LineLength
     /**
-     * Location of the scm publication tree:
-     * <code>scm:&lt;scm_provider&gt;&lt;delimiter&gt;&lt;provider_specific_part&gt;</code>.
+     * URL of the target SCM repository to publish to in format
+     * {@code scm:<scm_provider><delimiter><provider_specific_part>}.
+     * <p>
      * Example:
-     * <code>scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin-LATEST/</code>
+     * {@code scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin-LATEST/}
+     *
+     * @see <a href="https://maven.apache.org/scm/scm-url-format.html">SCM URL Format</a>
      */
     // CHECKSTYLE_ON: LineLength
     @Parameter(
@@ -79,15 +82,15 @@ public abstract class AbstractScmPublishMojo extends AbstractMojo {
     protected String pubScmUrl;
 
     /**
-     * If the checkout directory exists and this flag is activated, the plugin will try an SCM-update instead
-     * of delete then checkout.
+     * If the {@link AbstractScmPublishMojo#checkoutDirectory} exists and this flag is activated, the plugin will try an SCM-update instead
+     * of deleting first and then doing a fresh checkout.
      */
     @Parameter(property = "scmpublish.tryUpdate", defaultValue = "false")
     protected boolean tryUpdate;
 
     // CHECKSTYLE_OFF: LineLength
     /**
-     * Location where the scm check-out is done. By default, scm checkout is done in build (target) directory,
+     * Filesystem path of the directory to where the scm check-out is done. By default, scm checkout is done in build (target) directory,
      * which is deleted on every <code>mvn clean</code>. To avoid this and get better performance, configure
      * this location outside build structure and set <code>tryUpdate</code> to <code>true</code>.
      * See <a href="http://maven.apache.org/plugins/maven-scm-publish-plugin/various-tips.html#Improving_SCM_Checkout_Performance">
@@ -107,13 +110,13 @@ public abstract class AbstractScmPublishMojo extends AbstractMojo {
     protected String subDirectory;
 
     /**
-     * Display list of added, deleted, and changed files, but do not do any actual SCM operations.
+     * If set to {@true} displays list of added, deleted, and changed files, but does not do any actual SCM operations.
      */
     @Parameter(property = "scmpublish.dryRun")
     private boolean dryRun;
 
     /**
-     * Set this to 'true' to skip site deployment.
+     * Set this to {@code true} to skip site deployment.
      *
      * @deprecated Please use {@link #skipDeployment}.
      */
@@ -122,13 +125,13 @@ public abstract class AbstractScmPublishMojo extends AbstractMojo {
     private boolean skipDeployement;
 
     /**
-     * Set this to 'true' to skip site deployment.
+     * Set this to {@code true} to skip site deployment.
      */
     @Parameter(property = "scmpublish.skipDeploy", alias = "maven.site.deploy.skip", defaultValue = "false")
     private boolean skipDeployment;
 
     /**
-     * Run add and delete commands, but leave the actually checkin for the user to run manually.
+     * Only executes local SCM add and delete commands, but leave the actual checkin for the user to run manually.
      */
     @Parameter(property = "scmpublish.skipCheckin")
     private boolean skipCheckin;
@@ -146,7 +149,7 @@ public abstract class AbstractScmPublishMojo extends AbstractMojo {
     protected String excludes;
 
     /**
-     * Patterns to include in the scm tree.
+     * Patterns to include in the scm checkout.
      */
     @Parameter
     protected String includes;
@@ -212,7 +215,7 @@ public abstract class AbstractScmPublishMojo extends AbstractMojo {
     protected String siteOutputEncoding;
 
     /**
-     * Do not delete files to the scm
+     * If set to {@code true} does not delete files in the SCM that are not in the site.
      */
     @Parameter(property = "scmpublish.skipDeletedFiles", defaultValue = "false")
     protected boolean skipDeletedFiles;
@@ -235,14 +238,25 @@ public abstract class AbstractScmPublishMojo extends AbstractMojo {
     protected Settings settings;
 
     /**
-     * Collections of paths not to delete when checking content to delete.
-     * If your site has subdirectories published by an other mechanism/build
+     * Collections of path patterns specifying files/directories which should never be deleted by this goal.
+     * Each pattern is either
+     * <ul>
+     * <li>an Ant pattern (when surrounded by {@code %ant[} and {@code ]} or not starting with {@code %regex[}), or</li>
+     * <li>a full regex pattern when surrounded by  {@code %regex[} and {@code ]}.</li>
+     * </ul>
+     * Files/directories with a matching path will be skipped when deleting files from the SCM.
+     * <p>
+     * If your site has subdirectories or individual files published by an other mechanism/build you should leverage this parameter.
+     * @see <a href="http://ant.apache.org/manual/dirtasks.html#patterns">Ant Patterns</a>
+     * @see org.codehaus.plexus.util.MatchPatterns
+     * @see #skipDeletedFiles
      */
     @Parameter
     protected String[] ignorePathsToDelete;
 
     /**
-     * SCM branch to use. For github, you must configure with <code>gh-pages</code>.
+     * SCM branch to use. For using with <a href="https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch">GitHub Pages</a>,
+     * you conventionally use <code>gh-pages</code>.
      */
     @Parameter(property = "scmpublish.scm.branch")
     protected String scmBranch;
@@ -254,13 +268,14 @@ public abstract class AbstractScmPublishMojo extends AbstractMojo {
     protected boolean automaticRemotePathCreation;
 
     /**
-     * Filename extensions of files which need new line normalization.
+     * File name extensions of files where line ending normalization should be applied.
+     * @see #extraNormalizeExtensions
      */
     private static final String[] NORMALIZE_EXTENSIONS = {"html", "css", "js"};
 
     /**
-     * Extra file extensions to normalize line ending (will be added to default
-     * <code>html</code>,<code>css</code>,<code>js</code> list)
+     * Additional file name extensions of files where line ending normalization should be applied (will be added to the default list containing
+     * <code>html</code>,<code>css</code> and <code>js</code>)
      */
     @Parameter
     protected String[] extraNormalizeExtensions;

src/main/java/org/apache/maven/plugins/scmpublish/ScmPublishPublishScmMojo.java

@@ -48,20 +48,20 @@
 import org.codehaus.plexus.util.MatchPatterns;
 
 /**
- * Publish a content to scm. By default, content is taken from default site staging directory
+ * Publish content to an SCM (source code management) repository (like Git). By default, content is taken from default site staging directory
  * <code>${project.build.directory}/staging</code>.
- * Can be used without project, so usable to update any SCM with any content.
+ * Can also be used without a Maven project, so usable to update any SCM with any content.
+ * @see <a href="https://maven.apache.org/scm/index.html">Maven SCM</a>
  */
 @Mojo(name = "publish-scm", aggregator = true, requiresProject = false)
 public class ScmPublishPublishScmMojo extends AbstractScmPublishMojo {
     /**
-     * The content to be published.
+     * The path of the directory containing the content to be published.
+     * The is published recursively (i.e. including subdirectories).
      */
     @Parameter(property = "scmpublish.content", defaultValue = "${project.build.directory}/staging")
     private File content;
 
-    /**
-     */
     @Parameter(defaultValue = "${project}", readonly = true, required = true)
     protected MavenProject project;
 

src/site/apt/index.apt.vm

@@ -29,7 +29,7 @@
 ${project.name}
 
     The maven-scm-publish-plugin is a utility plugin to allow publishing Maven
-    website to any supported SCM.
+    website to any supported SCM (Source Code Management) repository (like Git).
     The primary goal was to have an utility plugin to allow Apache projects
     to publish Maven websites via the {{{https://infra.apache.org/project-site.html#tools}ASF svnpubsub system}}.