From 2b12aab7e1de5d0b23df51fbb958d7b44d859c52 Mon Sep 17 00:00:00 2001
From: Benjamin Bentmann <bentmann@apache.org>
Date: Tue, 2 Jun 2009 19:39:12 +0000
Subject: [PATCH] o Extended API docs

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@781137 13f79535-47bb-0310-9956-ffa450edef68
---
 .../java/org/apache/maven/model/ModelBuildingRequest.java   | 6 ++++--
 .../maven/model/inheritance/InheritanceAssembler.java       | 4 +++-
 .../org/apache/maven/model/profile/ProfileInjector.java     | 3 ++-
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/maven-model-builder/src/main/java/org/apache/maven/model/ModelBuildingRequest.java b/maven-model-builder/src/main/java/org/apache/maven/model/ModelBuildingRequest.java
index 32ec452c40..bb7646c1ab 100644
--- a/maven-model-builder/src/main/java/org/apache/maven/model/ModelBuildingRequest.java
+++ b/maven-model-builder/src/main/java/org/apache/maven/model/ModelBuildingRequest.java
@@ -25,7 +25,7 @@ import java.util.Properties;
 import org.apache.maven.model.profile.ProfileActivationContext;
 
 /**
- * Collects settings that control building of effective models.
+ * Collects settings that control the building of effective models.
  * 
  * @author Benjamin Bentmann
  */
@@ -41,7 +41,9 @@ public interface ModelBuildingRequest
     boolean istLenientValidation();
 
     /**
-     * Sets the level of validation to perform on processed models. By default, models are validated in strict mode.
+     * Sets the level of validation to perform on processed models. For building of projects, strict validation should
+     * be used to ensure proper building. For the mere retrievel of dependencies during artifact resolution, lenient
+     * validation should be used to account for models of poor quality. By default, models are validated in strict mode.
      * 
      * @param lenientValidation A flag whether validation should be lenient instead of strict. For building of projects,
      *            strict validation should be used to ensure proper building. For the mere retrievel of dependencies
diff --git a/maven-model-builder/src/main/java/org/apache/maven/model/inheritance/InheritanceAssembler.java b/maven-model-builder/src/main/java/org/apache/maven/model/inheritance/InheritanceAssembler.java
index dfd1b8e855..4885e88248 100644
--- a/maven-model-builder/src/main/java/org/apache/maven/model/inheritance/InheritanceAssembler.java
+++ b/maven-model-builder/src/main/java/org/apache/maven/model/inheritance/InheritanceAssembler.java
@@ -31,7 +31,9 @@ public interface InheritanceAssembler
 {
 
     /**
-     * Merges values from the specified parent model into the given child model.
+     * Merges values from the specified parent model into the given child model. Implementations are expected to keep
+     * parent and child completely decoupled by injecting deep copies of objects into the child rather than the original
+     * objects from the parent.
      * 
      * @param child The child model into which to merge the values inherited from the parent, must not be
      *            <code>null</code>.
diff --git a/maven-model-builder/src/main/java/org/apache/maven/model/profile/ProfileInjector.java b/maven-model-builder/src/main/java/org/apache/maven/model/profile/ProfileInjector.java
index 20db52a478..b76846d698 100644
--- a/maven-model-builder/src/main/java/org/apache/maven/model/profile/ProfileInjector.java
+++ b/maven-model-builder/src/main/java/org/apache/maven/model/profile/ProfileInjector.java
@@ -32,7 +32,8 @@ public interface ProfileInjector
 {
 
     /**
-     * Merges values from the specified profile into the given model.
+     * Merges values from the specified profile into the given model. Implementations are expected to keep the profile
+     * and model completely decoupled by injecting deep copies rather than the original objects from the profile.
      * 
      * @param model The model into which to merge the values defined by the profile, must not be <code>null</code>.
      * @param profile The (read-only) profile whose values should be injected, may be <code>null</code>.