svn commit: r1201722 - /maven/archetype/trunk/maven-archetype-plugin/src/main/java/org/apache/maven/archetype/mojos/CreateArchetypeFromProjectMojo.java

[bi...@apache.org]

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
 
     /**