merged 541186 from branch (MNG-2461: Write JavaDoc documentation)

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@541187 13f79535-47bb-0310-9956-ffa450edef68

maven-settings/src/main/java/org/apache/maven/settings/MavenSettingsBuilder.java

@@ -25,6 +25,12 @@ import java.io.File;
 import java.io.IOException;
 
 /**
+ * Builder for the user or global settings. By default, the settings files are located:
+ * <ul>
+ * <li>user settings: ${user.home}/settings.xml</li>
+ * <li>global settings: ${maven.home}/conf/settings.xml</li>
+ * </ul>
+ *
  * @author jdcasey
  * @version $Id$
  */
@@ -33,6 +39,12 @@ public interface MavenSettingsBuilder
     String ROLE = MavenSettingsBuilder.class.getName();
 
     /**
+     *
+     * @param userSettingsFile
+     * @param globalSettingsFile
+     * @return a <code>Settings</code> object from the user and global settings file.
+     * @throws IOException if any
+     * @throws XmlPullParserException if any
      * @since 2.1
      */
     Settings buildSettings( File userSettingsFile, File globalSettingsFile )

maven-settings/src/main/java/org/apache/maven/settings/RuntimeInfo.java

@@ -24,9 +24,13 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * To handle runtime informations like local repository or profiles.
+ *
+ * @version $Id$
+ */
 public class RuntimeInfo
 {
-
     private List locations = new ArrayList();
 
     // using Boolean for 3VL (null for not-set, otherwise override with value)
@@ -48,46 +52,75 @@ public class RuntimeInfo
 
     private final Settings settings;
 
+    /**
+     * @param settings
+     */
     public RuntimeInfo( Settings settings )
     {
         this.settings = settings;
     }
 
+    /**
+     * @param path
+     */
     public void addLocation( String path )
     {
         this.locations.add( path );
     }
 
+    /**
+     * @return
+     */
     public List getLocations()
     {
         return locations;
     }
 
+    /**
+     * @param pluginUpdateForced
+     */
     public void setPluginUpdateOverride( Boolean pluginUpdateForced )
     {
         this.pluginUpdateForced = pluginUpdateForced;
     }
 
+    /**
+     * @return
+     */
     public Boolean getPluginUpdateOverride()
     {
         return pluginUpdateForced;
     }
 
+    /**
+     * @return
+     */
     public Boolean getApplyToAllPluginUpdates()
     {
         return applyToAllPluginUpdates;
     }
 
+    /**
+     * @param applyToAll
+     */
     public void setApplyToAllPluginUpdates( Boolean applyToAll )
     {
         this.applyToAllPluginUpdates = applyToAll;
     }
 
+    /**
+     * @param activeProfile
+     * @param sourceLevel
+     */
     public void setActiveProfileSourceLevel( String activeProfile, String sourceLevel )
     {
         activeProfileToSourceLevel.put( activeProfile, sourceLevel );
     }
 
+    /**
+     * @param activeProfile
+     * @return
+     */
     public String getSourceLevelForActiveProfile( String activeProfile )
     {
         String sourceLevel = (String) activeProfileToSourceLevel.get( activeProfile );
@@ -102,11 +135,19 @@ public class RuntimeInfo
         }
     }
 
+    /**
+     * @param pluginGroupId
+     * @param sourceLevel
+     */
     public void setPluginGroupIdSourceLevel( String pluginGroupId, String sourceLevel )
     {
         pluginGroupIdSourceLevels.put( pluginGroupId, sourceLevel );
     }
 
+    /**
+     * @param pluginGroupId
+     * @return
+     */
     public String getSourceLevelForPluginGroupId( String pluginGroupId )
     {
         String sourceLevel = (String) pluginGroupIdSourceLevels.get( pluginGroupId );
@@ -121,14 +162,19 @@ public class RuntimeInfo
         }
     }
 
+    /**
+     * @param localRepoSourceLevel
+     */
     public void setLocalRepositorySourceLevel( String localRepoSourceLevel )
     {
         this.localRepositorySourceLevel = localRepoSourceLevel;
     }
 
+    /**
+     * @return
+     */
     public String getLocalRepositorySourceLevel()
     {
         return localRepositorySourceLevel;
     }
-
 }

maven-settings/src/main/java/org/apache/maven/settings/SettingsUtils.java

@@ -28,6 +28,12 @@ import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Several convenience methods to handle settings
+ *
+ * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
+ * @version $Id$
+ */
 public final class SettingsUtils
 {
     private SettingsUtils()
@@ -35,6 +41,11 @@ public final class SettingsUtils
         // don't allow construction.
     }
 
+    /**
+     * @param dominant
+     * @param recessive
+     * @param recessiveSourceLevel
+     */
     public static void merge( Settings dominant, Settings recessive, String recessiveSourceLevel )
     {
         if ( dominant == null || recessive == null )
@@ -126,6 +137,11 @@ public final class SettingsUtils
 
     }
 
+    /**
+     * @param dominant
+     * @param recessive
+     * @param recessiveSourceLevel
+     */
     private static void shallowMergeById( List dominant, List recessive, String recessiveSourceLevel )
     {
         Map dominantById = mapById( dominant );
@@ -143,6 +159,10 @@ public final class SettingsUtils
         }
     }
 
+    /**
+     * @param identifiables
+     * @return a map
+     */
     private static Map mapById( List identifiables )
     {
         Map byId = new HashMap();
@@ -157,6 +177,10 @@ public final class SettingsUtils
         return byId;
     }
 
+    /**
+     * @param settingsProfile
+     * @return a profile
+     */
     public static org.apache.maven.model.Profile convertFromSettingsProfile( Profile settingsProfile )
     {
         org.apache.maven.model.Profile profile = new org.apache.maven.model.Profile();
@@ -239,6 +263,10 @@ public final class SettingsUtils
         return profile;
     }
 
+    /**
+     * @param settingsRepo
+     * @return a repository
+     */
     private static org.apache.maven.model.Repository convertFromSettingsRepository( Repository settingsRepo )
     {
         org.apache.maven.model.Repository repo = new org.apache.maven.model.Repository();
@@ -260,6 +288,10 @@ public final class SettingsUtils
         return repo;
     }
 
+    /**
+     * @param settingsPolicy
+     * @return a RepositoryPolicy
+     */
     private static org.apache.maven.model.RepositoryPolicy convertRepositoryPolicy( RepositoryPolicy settingsPolicy )
     {
         org.apache.maven.model.RepositoryPolicy policy = new org.apache.maven.model.RepositoryPolicy();
@@ -268,5 +300,4 @@ public final class SettingsUtils
         policy.setChecksumPolicy( settingsPolicy.getChecksumPolicy() );
         return policy;
     }
-
 }

maven-settings/src/main/mdo/settings.mdo

@@ -89,6 +89,10 @@
       <name>IdentifiableBase</name>
       <superClass>TrackableBase</superClass>
       <version>1.0.0</version>
+      <description>
+        <![CDATA[
+        Base class for <code>Mirror</code>, <code>Profile</code>, <code>Proxy</code> and <code>Server</code>.
+        ]]></description>
       <fields>
         <field>
           <name>id</name>
@@ -272,11 +276,17 @@
 
     private Proxy activeProxy;
 
+    /**
+     * Reset the <code>activeProxy</code> field to <code>null</code>
+     */
     public void flushActiveProxy()
     {
         this.activeProxy = null;
     }
 
+    /**
+     * @return the first active proxy
+     */
     public synchronized Proxy getActiveProxy()
     {
         if(activeProxy == null)
@@ -351,11 +361,18 @@
 
     private java.util.Map profileMap;
 
+    /**
+     * Reset the <code>profileMap</code> field to <code>null</code>
+     */
     public void flushProfileMap()
     {
         this.profileMap = null;
     }
 
+    /**
+     * @return a Map of profiles field with <code>Profile#getId()</code> as key
+     * @see org.apache.maven.settings.Profile#getId()
+     */
     public java.util.Map getProfilesAsMap()
     {
         if ( profileMap == null )
@@ -428,6 +445,10 @@
       <name>Proxy</name>
       <version>1.0.0</version>
       <superClass>IdentifiableBase</superClass>
+      <description>
+        <![CDATA[
+        The <code>&lt;proxy&gt;</code> element contains informations required to a proxy settings.
+        ]]></description>
       <fields>
         <field>
           <name>active</name>
@@ -510,6 +531,10 @@
       <name>Server</name>
       <version>1.0.0</version>
       <superClass>IdentifiableBase</superClass>
+      <description>
+        <![CDATA[
+        The <code>&lt;server&gt;</code> element contains informations required to a server settings.
+        ]]></description>
       <fields>
         <field>
           <name>username</name>
@@ -847,6 +872,9 @@
           <version>1.0.0</version>
           <code>
             <![CDATA[
+    /**
+     * @see java.lang.Object#equals(java.lang.Object)
+     */
     public boolean equals( Object obj )
     {
         RepositoryBase other =  (RepositoryBase) obj;
@@ -902,6 +930,9 @@
           <version>1.0.0</version>
           <code>
             <![CDATA[
+    /**
+     * @see org.apache.maven.settings.RepositoryBase#equals(java.lang.Object)
+     */
     public boolean equals( Object obj )
     {
         return super.equals( obj );
@@ -942,7 +973,7 @@
           <version>1.0.0</version>
           <description>
             What to do when verification of an artifact checksum fails -
-            warn, fail, etc. Valid values are "fail" or "warn"
+            warn, fail, etc. Valid values are "fail" or "warn".
           </description>
           <type>String</type>
         </field>
@@ -966,7 +997,7 @@
           <type>String</type>
           <required>true</required>
           <description>
-            The name of the property to be used to activate a profile
+            The name of the property to be used to activate a profile.
           </description>
         </field>
         <field>
@@ -974,7 +1005,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            The value of the property to be used to activate a profile
+            The value of the property to be used to activate a profile.
           </description>
         </field>
       </fields>
@@ -994,7 +1025,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            The name of the OS to be used to activate a profile
+            The name of the OS to be used to activate a profile.
           </description>
         </field>
         <field>
@@ -1011,7 +1042,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            The architecture of the OS to be used to activate a profile
+            The architecture of the OS to be used to activate a profile.
           </description>
         </field>
         <field>
@@ -1019,7 +1050,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            The version of the OS to be used to activate a profile
+            The version of the OS to be used to activate a profile.
           </description>
         </field>
       </fields>
@@ -1041,7 +1072,7 @@
           <type>String</type>
           <description>
             The name of the file that should be missing to activate a
-            profile
+            profile.
           </description>
         </field>
         <field>
@@ -1049,7 +1080,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            The name of the file that should exist to activate a profile
+            The name of the file that should exist to activate a profile.
           </description>
         </field>
       </fields>