Author: bimargulies
Date: Mon Nov 14 14:26:16 2011
New Revision: 1201722
URL: http://svn.apache.org/viewvc?rev=1201722&view=rev
Log:
ARCHETYPE-390: Several parameters of the create-from-project mojo lack
documentation
o added a barge-load of documentation to the create-from-project mojo.
Modified:
maven/archetype/trunk/maven-archetype-plugin/src/main/java/org/apache/maven/archetype/mojos/CreateArchetypeFromProjectMojo.java
Modified:
maven/archetype/trunk/maven-archetype-plugin/src/main/java/org/apache/maven/archetype/mojos/CreateArchetypeFromProjectMojo.java
URL:
http://svn.apache.org/viewvc/maven/archetype/trunk/maven-archetype-plugin/src/main/java/org/apache/maven/archetype/mojos/CreateArchetypeFromProjectMojo.java?rev=1201722&r1=1201721&r2=1201722&view=diff
==============================================================================
---
maven/archetype/trunk/maven-archetype-plugin/src/main/java/org/apache/maven/archetype/mojos/CreateArchetypeFromProjectMojo.java
(original)
+++
maven/archetype/trunk/maven-archetype-plugin/src/main/java/org/apache/maven/archetype/mojos/CreateArchetypeFromProjectMojo.java
Mon Nov 14 14:26:16 2011
@@ -40,7 +40,47 @@ import java.util.List;
import java.util.Properties;
/**
- * Creates an archetype project from the current project, with a
<code>basic</code> integration-test.
+ * <p>
+ * Creates an archetype project from the current project.
+ * </p>
+ * <p>
+ * This goal reads your source and resource files, the values of its
parameters,
+ * and properties you specify in a <code>.property</code> file, and uses them
to
+ * create a Maven archetype project using the maven-archetype packaging.
+ * If you build the resulting project, it will create the archetype. You can
then
+ * use this archetype to create new projects that resemble the original.
+ * </p>
+ * <p>
+ * The maven-archetype-plugin uses Velocity to expand template files, and this
documentation
+ * talks about 'Velocity Properties', which are values substituted into
Velocity templates.
+ * See <a href="http://velocity.apache.org/engine/devel/user-guide.html";>The
Velocity User's Guide</a>
+ * for more information.
+ * </p>
+ * <p>
+ * This goal modifies the text of the files of the current project to form the
Velocity template files
+ * that make up the archetype.
+ * </p>
+ * <dl>
+ * <dt>GAV</dt><dd>The GAV values for the current project are replaced by
properties: groupId, artifactId, and version.
+ * The user chooses new values for these when generating a project from the
archetype.</dd>
+ * <dt>package</dt><dd>All the files under one specified Java (or cognate)
package are relocated to a project
+ * that the user chooses when generating a project. References to the class
name are replaced by a property reference. For
+ * example, if the current project's sources are in the package
<code>org.apache.saltedpeanuts</code>, then
+ * any example of the string <code>org.apache.saltedpeanuts</code> is replaced
with the Velocity property
+ * reference <code>${packageName}</code>. When the user generates a project,
this is in turn replaced by
+ * his or her choice of a package.
+ * </dd>
+ * <dt>custom properties</dt><dd>You may identify additional strings that
should be replaced by parameters.
+ * To add custom properties, you must use the <code>propertyFile</code>
parameter to specify a property file.
+ * See the documentation for <code>propertyFile</code> for the details.
+ * </dl>
+ * <p>
+ * Note that you may need to edit the results of this goal. This goal has no
way to exclude unwanted files,
+ * or add copyright notices to the Velocity templates, or add more complex
elements to the archetype metadata file.
+ * </p>
+ * <p>
+ * This goal also generates a simple integration-test that exercises the
generated archetype.
+ * </p>
*
* @author rafale
* @requiresProject true
@@ -107,7 +147,9 @@ public class CreateArchetypeFromProjectM
*/
private boolean preserveCData = false;
- /** @parameter expression="${localRepository}" */
+ /** @parameter expression="${localRepository}"
+ * @readonly
+ **/
private ArtifactRepository localRepository;
/**
@@ -128,7 +170,39 @@ public class CreateArchetypeFromProjectM
private MavenProject project;
/**
- * The property file that holds the plugin configuration.
+ * The property file that holds the plugin configuration. If this is
provided, then
+ * the plugin reads properties from here. The properties in here can be
standard
+ * properties listed below or custom properties for this archetype. The
standard properties
+ * are below. Several of them overlap parameters of this goal; it's better
to just
+ * set the parameter.
+ *
+ * <dl><dt>package</dt><dd>See the packageName parameter.</dd>
+ * <dt>archetype.languages</dt><dd>See the archetypeLanguages
parameter.</dd>
+ * <dt>groupId</dt><dd>The default groupId of the generated project.</dd>
+ * <dt>artifactId</dt><dd>The default artifactId of the generated
project.</dd>
+ * <dt>version</dt><dd>The default version of the generated project.</dd>
+ * <dt>archetype.filteredExtensions</dt><dd>See the filteredExensions
parameter.</dd>
+ * </dl>
+ * <strong>Custom Properties</strong>
+ * <p>
+ * Custom properties allow you to replace some constant values in the
project's files
+ * with Velocity macro references. When a user generates a project from
your archetype
+ * he or she gets the opportunity to replace the value from the source
project.
+ * </p>
+ * <p>
+ * Custom property names <strong>may not contain the '.'
character</strong>.
+ * </p>
+ * <p>
+ * For example, if you include a line like the following in your property
file:
+ * <pre>
+ * cxf-version=2.5.1-SNAPSHOT
+ * </pre>
+ * the plugin will search your files for the string
<pre>2.5.1-SNAPSHOT</pre> and
+ * replace them with references to a velocity macro
<pre>cxf-version</pre>. It will
+ * then list <pre>cxf-version</pre> as a <pre>requiredProperty</pre> in
the
+ * archetype-metadata.xml, with <pre>2.5.1-SNAPSHOT</pre> as the default
value.
+ * </p>
+ *
*
* @parameter expression="${archetype.properties}"
*/
@@ -152,7 +226,11 @@ public class CreateArchetypeFromProjectM
/** @parameter expression="${testMode}" */
private boolean testMode;
- /** @parameter expression="${packageName}" */
+ /**
+ * The package name for Java source files to be incorporated in the
archetype and
+ * and relocated to the package that the user selects.
+ *
+ * @parameter expression="${packageName}" */
private String packageName; //Find a better way to resolve the package!!!
enforce usage of the configurator
/**
