svn commit: r781127 - /maven/components/trunk/maven-model-builder/src/main/java/org/apache/maven/model/interpolation/ModelInterpolator.java

[be...@apache.org]

Author: bentmann
Date: Tue Jun  2 19:10:40 2009
New Revision: 781127

URL: http://svn.apache.org/viewvc?rev=781127&view=rev
Log:
o Added some API docs

Modified:
    maven/components/trunk/maven-model-builder/src/main/java/org/apache/maven/model/interpolation/ModelInterpolator.java

Modified: maven/components/trunk/maven-model-builder/src/main/java/org/apache/maven/model/interpolation/ModelInterpolator.java
URL: http://svn.apache.org/viewvc/maven/components/trunk/maven-model-builder/src/main/java/org/apache/maven/model/interpolation/ModelInterpolator.java?rev=781127&r1=781126&r2=781127&view=diff
==============================================================================
--- maven/components/trunk/maven-model-builder/src/main/java/org/apache/maven/model/interpolation/ModelInterpolator.java (original)
+++ maven/components/trunk/maven-model-builder/src/main/java/org/apache/maven/model/interpolation/ModelInterpolator.java Tue Jun  2 19:10:40 2009
@@ -25,6 +25,9 @@
 import java.io.File;
 
 /**
+ * Replaces expressions of the form <tt>${token}</tt> with their effective values. Effective values are basically
+ * calculated from the elements of the model itself and the execution properties from the building request.
+ * 
  * @author jdcasey
  *         <p/>
  *         Created on Feb 2, 2005
@@ -32,10 +35,30 @@
 public interface ModelInterpolator
 {
 
+    /**
+     * The default format used for build timestamps.
+     */
     String DEFAULT_BUILD_TIMESTAMP_FORMAT = "yyyyMMdd-HHmm";
 
+    /**
+     * The name of a property that if present in the model's {@code <properties>} section specifies a custom format for
+     * build timestamps. See {@link java.text.SimpleDateFormat} for details on the format.
+     */
     String BUILD_TIMESTAMP_FORMAT_PROPERTY = "maven.build.timestamp.format";
 
+    /**
+     * Interpolates expressions in the specified model. Note that implementations are free to either interpolate the
+     * provided model directly or to create a clone of the model and interpolate the clone. Callers should always use
+     * the returned model and must not rely on the input model being updated.
+     * 
+     * @param model The model to interpolate, must not be {@code null}.
+     * @param projectDir The project directory, may be {@code null} if the model does not belong to a local project but
+     *            to some artifact's metadata.
+     * @param request The model building request that holds further settings, must not be {@code null}.
+     * @return The interpolated model, never {@code null}.
+     * @throws ModelInterpolationException If the model could not be interpolated (e.g. due to expressions with cyclic
+     *             references).
+     */
     Model interpolateModel( Model model, File projectDir, ModelBuildingRequest request )
         throws ModelInterpolationException;