o Polished documentation
git-svn-id: https://svn.apache.org/repos/asf/maven/plugins/trunk@642002 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/main/java/org/apache/maven/plugin/patch/ApplyMojo.java b/src/main/java/org/apache/maven/plugin/patch/ApplyMojo.java
index 94c63ac..d635603 100644
--- a/src/main/java/org/apache/maven/plugin/patch/ApplyMojo.java
+++ b/src/main/java/org/apache/maven/plugin/patch/ApplyMojo.java
@@ -92,7 +92,8 @@
/**
* The list of patch file names, supplying the order in which patches should be applied. The path names in this list
- * must be relative to the base directory specified by the parameter <code>patchDirectory</code>.
+ * must be relative to the base directory specified by the parameter <code>patchDirectory</code>. This parameter
+ * is mutually exclusive with the <code>patchfile</code> parameter.
*
* @parameter
*/
@@ -109,9 +110,9 @@
* Flag to enable/disable optimization file from being written. This file tracks the patches that were applied the
* last time this goal actually executed. It is required for cases where project-sources optimizations are enabled,
* since project-sources will not be re-unpacked if they are at least as fresh as the source archive. If we avoid
- * re-unpacking project sources, we need to make sure we don't reapply patches. This flag is true by default. <br/>
- * <b>NOTE:</b> If the list of patches changes and this flag is enabled, a `mvn clean` must be executed before the
- * next build, to remove the tracking file.
+ * re-unpacking project sources, we need to make sure we don't reapply patches.<br/> <strong>Note:</strong> If the
+ * list of patches changes and this flag is enabled, a "<code>mvn clean</code>" must be executed before the next
+ * build, to remove the tracking file.
*
* @parameter default-value="true"
*/
@@ -131,43 +132,42 @@
* The target directory for applying patches. Files in this directory will be modified.
*
* @parameter alias="patchTargetDir" default-value="${project.build.sourceDirectory}"
- * @required
*/
private File targetDirectory;
/**
- * true if the desired behavior is to fail the build on the first failed patch detected.
+ * Flag being <code>true</code> if the desired behavior is to fail the build on the first failed patch detected.
*
* @parameter default-value="true"
*/
private boolean failFast;
/**
- * Setting natural order processing to true will cause all patches in a directory to be processed in an natural
- * order alleviating the need to declare patches directly in the project file.
+ * Setting natural order processing to <code>true</code> will cause all patches in a directory to be processed in
+ * a natural order alleviating the need to declare patches directly in the project file.
*
* @parameter default-value="false"
*/
private boolean naturalOrderProcessing;
/**
- * When the strictPatching flag is set, this parameter is useful to mark certain contents of the patch-source
- * directory that should be ignored without causing the build to fail.
+ * When the <code>strictPatching</code> flag is set, this parameter is useful to mark certain contents of the
+ * patch-source directory that should be ignored without causing the build to fail.
*
* @parameter
*/
private List ignoredPatches;
/**
- * Flag that, when set to true, will make sure that all patches included in the 'patches' list must be present and
- * describe the full contents of the patch directory. If strictPatching is set to true, and the patches list has a
- * value that does not correspond to a file in the patch directory, the build will fail. If strictPatching is set to
- * true, and the patch directory contains files not listed in the patches parameter, the build will fail. If set to
- * false, only the patches listed in the patches parameter that have corresponding files will be applied; the rest
- * will be ignored. Default value for this parameter is false.
+ * Flag that, when set to <code>true</code>, will make sure that all patches included in the <code>patches</code>
+ * list must be present and describe the full contents of the patch directory. If <code>strictPatching</code> is
+ * set to <code>true</code>, and the <code>patches</code> list has a value that does not correspond to a file
+ * in the patch directory, the build will fail. If <code>strictPatching</code> is set to <code>true</code>, and
+ * the patch directory contains files not listed in the <code>patches</code> parameter, the build will fail. If
+ * set to <code>false</code>, only the patches listed in the <code>patches</code> parameter that have
+ * corresponding files will be applied; the rest will be ignored.
*
* @parameter default-value="false"
- * @required
*/
private boolean strictPatching;
@@ -175,56 +175,57 @@
* The number of directories to be stripped from patch file paths, before applying, starting from the leftmost, or
* root-est.
*
- * @parameter
+ * @parameter default-value="0"
*/
- private int strip = 0;
+ private int strip;
/**
* Whether to ignore whitespaces when applying the patches.
*
- * @parameter
+ * @parameter default-value="true"
*/
- private boolean ignoreWhitespace = true;
+ private boolean ignoreWhitespace;
/**
* Whether to treat these patches as having reversed source and dest in the patch syntax.
*
- * @parameter
+ * @parameter default-value="false"
*/
- private boolean reverse = false;
+ private boolean reverse;
/**
* Whether to make backups of the original files before modding them.
*
- * @parameter
+ * @parameter default-value="false"
*/
- private boolean backups = false;
+ private boolean backups;
/**
- * List of phrases to watch for in patch-command output. If one is found, it will cause the build to fail. All
- * phrases should be lower-case ONLY.
+ * List of phrases to watch for in the command output from the patch tool. If one is found, it will cause the build
+ * to fail. All phrases should be lower-case <em>only</em>. By default, the phrases <code>fail</code>,
+ * <code>skip</code> and <code>reject</code> are used.
*
* @parameter
*/
private List failurePhrases = PATCH_FAILURE_WATCH_PHRASES;
/**
- * The original file which will be modified by the patch. Mutually exclusive with <code>workDir</code>.
+ * The original file which will be modified by the patch. By default, the patch tool will automatically derive the
+ * original file from the header of the patch file.
*
* @parameter
*/
private File originalFile;
/**
- * The file which is the original file, plus modifications from the patch. Mutually exclusive with
- * <code>workDir</code>.
+ * The output file which is the original file, plus modifications from the patch.
*
* @parameter
*/
private File destFile;
/**
- * The single patch file to apply. Mutually exclusive with <code>patches</code>.
+ * The single patch file to apply. This parameter is mutually exclusive with the <code>patches</code> parameter.
*
* @parameter
*/
@@ -234,7 +235,6 @@
* The base directory for the file names specified by the parameter <code>patches</code>.
*
* @parameter default-value="src/main/patches"
- * @required
*/
private File patchDirectory;
diff --git a/src/site/apt/examples/multiple.apt b/src/site/apt/examples/multiple.apt
index badc306..7cb051d 100644
--- a/src/site/apt/examples/multiple.apt
+++ b/src/site/apt/examples/multiple.apt
@@ -29,10 +29,10 @@
Patch Multiple Files from Multiple Directories
- The <<<maven-patch-plugin>>> can be configured to apply sets of patches from multiple directories.
+ The Patch Plugin can be configured to apply sets of patches from multiple directories.
In the example below, the plugin is setup to apply all the patches in a <<<bugfix>>> directory with
optimization (will not reapply the same patch) and also from an <<<enhancement>>> directory. This
- scenario might crop up if you don't have commit access to a projects source yet need to apply
+ scenario might crop up if you don't have commit access to a project's source yet need to apply
bugfix and enhancement patches. The two different patch source directories are shown purely as
an example of what can be configured.
@@ -47,7 +47,7 @@
<artifactId>maven-patch-plugin</artifactId>
<version>1.0</version>
<configuration>
- <patchTargetDir>${moduleDirectory}</patchTargetDir>
+ <targetDirectory>${moduleDirectory}</targetDirectory>
<skipApplication>false</skipApplication>
</configuration>
<executions>
diff --git a/src/site/apt/examples/single.apt b/src/site/apt/examples/single.apt
index f6b6c42..efbad86 100644
--- a/src/site/apt/examples/single.apt
+++ b/src/site/apt/examples/single.apt
@@ -29,7 +29,7 @@
Patch a Single File
- The <<<maven-patch-plugin>>> can be configured to apply a single patch to a file as specified:
+ The Patch Plugin can be configured to apply a single patch to a file as specified:
+--------
<project>
@@ -38,7 +38,9 @@
[...]
<plugins>
<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-patch-plugin</artifactId>
+ <version>1.0</version>
<configuration>
<patches>
<patch>mylittle.patch</patch>
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 3d957af..6a61d2a 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -29,24 +29,28 @@
Maven 2 Patch Plugin
- The patch plugin is used to apply patches to source files.
+ The Patch Plugin is used to apply patches to source files.
* Goals Overview
- The patch plugin has a single goal that can apply either a single declared patch or a directory of patches. Application of an entire patch directory can be configured with various patch-inclusion, -exclusion, and -ordering options.
+ The Patch Plugin has a single goal that can apply either a single declared patch or a directory of patches.
+ Application of an entire patch directory can be configured with various patch-inclusion, -exclusion, and -ordering
+ options:
+
+ * {{{apply-mojo.html}patch:apply}} Applies one or more patches to project sources.
* Usage
- Instructions on the basic usage of the patch plugin can be found
- {{{usage.html}here}}.
+ Instructions on the basic usage of the Patch Plugin can be found on the
+ {{{usage.html}usage page}}.
* Examples
- To provide you with better understanding on some usages of the patch plugin,
+ To provide you with better understanding on some usages of the Patch Plugin,
you can take a look into the following examples:
* {{{examples/single.html}How to patch from a single file.}}
* {{{examples/multiple.html}How to patch from a directory of patches.}}
- []
\ No newline at end of file
+ []
diff --git a/src/site/apt/usage.apt b/src/site/apt/usage.apt
index afcc345..43b5401 100644
--- a/src/site/apt/usage.apt
+++ b/src/site/apt/usage.apt
@@ -29,13 +29,13 @@
Usage
- The maven-patch-plugin attempts to use the gnu patch tool to apply patch files
+ The Patch Plugin attempts to use the {{{http://www.gnu.org/software/patch/}GNU patch tool}} to apply patch files
to source code. It can be configured to apply patch files from any number of
directories with a number of different policies including strict patching where
you must declare all patches in the plugin configuration to a natural order processing
which will apply all patching in a directory following a natural string sorted order.
- This plugin is most commonly used during the process-sources phase of the Maven lifecycle.
+ This plugin is most commonly used during the <<<process-sources>>> phase of the default build lifecycle:
+-----
mvn process-sources
@@ -47,7 +47,9 @@
<build>
<plugins>
<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-patch-plugin</artifactId>
+ <version>1.0</version>
<configuration>
<patches>
<patch>mylittle.patch</patch>
@@ -66,4 +68,4 @@
</build>
[...]
</project>
-+-----
\ No newline at end of file
++-----
