maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jvan...@apache.org
Subject svn commit: r390243 [2/3] - in /maven/components/branches/maven-embedder-refactor: ./ integration-tests/maven-core-it-plugin/src/main/java/org/apache/maven/plugin/coreit/ maven-core-it/ maven-core-it/it0043/ maven-core-it/it0059/src/test/ maven-core-it...
Date Thu, 30 Mar 2006 21:25:19 GMT
Modified: maven/components/branches/maven-embedder-refactor/maven-model/maven.mdo
URL: http://svn.apache.org/viewcvs/maven/components/branches/maven-embedder-refactor/maven-model/maven.mdo?rev=390243&r1=390242&r2=390243&view=diff
==============================================================================
--- maven/components/branches/maven-embedder-refactor/maven-model/maven.mdo (original)
+++ maven/components/branches/maven-embedder-refactor/maven-model/maven.mdo Thu Mar 30 13:25:09 2006
@@ -45,11 +45,8 @@
       <name>Model</name>
       <superClass>ModelBase</superClass>
       <description><![CDATA[
-         The <code>&lt;project&gt;</code> element specifies various attributes 
-         about a project. This is the root element of the project descriptor. 
-         The following table lists all of the possible child elements. Child 
-         elements with children are then documented further in subsequent 
-         sections.
+         The <code>&lt;project&gt;</code> element is the root of the descriptor.
+         The following table lists all of the possible child elements.
       ]]></description>
       <version>3.0.0+</version>
       <fields>
@@ -60,16 +57,19 @@
             The location of the parent project, if one exists. Values from the 
             parent project will be the default for this project if they are 
             left unspecified. The path may be absolute, or relative to the 
-            current project.xml file.
-            
-            <div class="source"><pre>&lt;extend&gt;${basedir}/../project.xml&lt;/extend&gt;</pre></div>
+            current <code>project.xml</code> file. For example,
+            <code>&lt;extend&gt;${basedir}/../project.xml&lt;/extend&gt;</code>.
           ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>parent</name>
           <version>4.0.0</version>
-          <description><![CDATA[Information on which parent POM to extend.]]></description>
+          <description><![CDATA[
+            The location of the parent project, if one exists. Values from the
+            parent project will be the default for this project if they are
+            left unspecified. The location is given as a group ID, artifact ID and version.
+          ]]></description>
           <association>
             <type>Parent</type>
           </association>
@@ -87,45 +87,38 @@
           <version>3.0.0</version>
           <required>true</required>
           <type>String</type>
-          <description><![CDATA[
-            The current version of the Maven project descriptor. This version 
-            number enables Maven to automatically update an out-of-date project 
-            descriptor when a new version is available. This version number 
-            should not be changed after the descriptor has been created. Maven 
-            will update it automatically.
-          ]]></description>
+          <description>
+            <![CDATA[Declares to which version of project descriptor this POM conforms. The only valid value is <code>3</code>.]]></description>
         </field>
         <field>
-          <name>id</name>
-          <version>3.0.0</version>
+          <name>groupId</name>
+          <version>3.0.0+</version>
           <required>true</required>
           <description><![CDATA[
-            The short name of the project.  This value is used when naming 
-            <a href="/plugins/java/index.html">jars</a> and 
-            <a href="/plugins/dist/index.html">distribution files</a>.
+            A universally unique identifier for a project. It is normal to
+            use a fully-qualified package name to distinguish it from other projects with a similar name
+            (eg. <code>org.apache.maven</code>).
           ]]></description>
           <type>String</type>
         </field>
         <field>
-          <name>groupId</name>
+          <name>artifactId</name>
           <version>3.0.0+</version>
           <required>true</required>
           <description><![CDATA[
-            The short name of the project group. This value is used to group
-            all jars for a project in one directory. For more info look at the
-            <a href="/reference/conventions.html">user guide</a>.
+            The identifier for this artifact that is unique within the group given by the group ID.
+            An artifact is something that is either produced or used by a project. Examples of artifacts produced by
+            Maven for a project include: JARs, source and binary distributions, and WARs.
           ]]></description>
           <type>String</type>
         </field>
         <field>
-          <name>artifactId</name>
-          <version>3.0.0+</version>
+          <name>id</name>
+          <version>3.0.0</version>
           <required>true</required>
           <description><![CDATA[
-            The short name of the project.  This value is used in conjunction
-            with <code>groupId</code>
-            when naming <a href="/plugins/java/index.html">jars</a> and 
-            <a href="/plugins/dist/index.html">distribution files</a>.
+            <b>Deprecated</b>. When used, this sets both the <code>groupId</code> and <code>artifactId</code> elements
+            if they were previously empty.
           ]]></description>
           <type>String</type>
         </field>
@@ -133,19 +126,13 @@
           <name>packaging</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            The type of artifact this project produces.
-            The main types are:
-            <ul>
-              <li>jar</li>
-              <li>war</li>
-              <li>ear</li>
-              <li>pom</li>
-            </ul>
-            <p>
-            However, plugins can create their own packaging, and
+            The type of artifact this project produces, for example <code>jar</code>
+              <code>war</code>
+              <code>ear</code>
+              <code>pom</code>.
+            Plugins can create their own packaging, and
             therefore their own packaging types,
-            so this list can not contain all possible types.
-            </p>
+            so this list does not contain all possible types.
           ]]></description>
           <type>String</type>
           <defaultValue>jar</defaultValue>
@@ -155,18 +142,14 @@
           <version>3.0.0+</version>
           <required>true</required>
           <description><![CDATA[
-            The full name of the project.  This value is used when
-            generating <a href="/plugins/javadoc/index.html">JavaDoc</a>
-            titles.
+            The full name of the project.
           ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>currentVersion</name>
           <description><![CDATA[
-            The current version of the project.  This value is used when
-            naming <a href="/plugins/java/index.html">jars</a> and 
-            <a href="/plugins/dist/index.html">distribution files</a>.
+            The current version of the artifact produced by this project.
           ]]></description>
           <version>3.0.0</version>
           <required>true</required>
@@ -194,14 +177,11 @@
           <name>description</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            Optional. A detailed description of the project. 
-            This description is used as the default to generate the
-            <a href="/plugins/site/index.html">Mailing Lists</a> of the project's 
-            web site, and is shown when <code>maven --usage</code> is called on 
-            the project. While this element can be specified as CDATA to enable 
-            the use of HTML tags within the description, you are encouraged to 
-            provide an alternative home page using <code>xdocs/index.xml</code> 
-            if this is required.
+            A detailed description of the project, used by Maven whenever it needs to describe the project,
+            such as on the web site. While this element can be specified as CDATA to enable
+            the use of HTML tags within the description, it is discouraged to allow plain text representation.
+            If you need to modify the index page of the generated web site, you are able to specify your own instead
+            of adjusting this text.
           ]]></description>
           <type>String</type>
         </field>
@@ -217,7 +197,7 @@
           <name>logo</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            The URL to the project's logo image.  This can be an URL relative
+            The URL of the project's logo image.  This can be an URL relative
             to the base directory of the generated web site,
             (e.g., <code>/images/project-logo.png</code>) or an absolute URL
             (e.g., <code>http://my.corp/project-logo.png</code>).  This is used
@@ -239,14 +219,14 @@
           <name>issueTrackingUrl</name>
           <version>3.0.0</version>
           <description><![CDATA[
-             Optional. The URL to the project's issue tracking system.
+             The URL of the project's issue tracking system.
           ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>issueManagement</name>
           <version>4.0.0</version>
-          <description><![CDATA[The project's issue management information.]]></description>
+          <description><![CDATA[The project's issue management system information.]]></description>
           <association>
             <type>IssueManagement</type>
           </association>
@@ -254,7 +234,7 @@
         <field>
           <name>ciManagement</name>
           <version>4.0.0</version>
-          <description><![CDATA[The project's continuous integration management information.]]></description>
+          <description><![CDATA[The project's continuous integration information.]]></description>
           <association>
             <type>CiManagement</type>
           </association>
@@ -264,9 +244,8 @@
           <version>3.0.0+</version>
           <required>true</required>
           <description><![CDATA[
-            The year of the project's inception specified with 4 digits.
-            This value is used when generating 
-            <a href="/plugins/javadoc/index.html">JavaDoc</a> copyright notices.
+            The year of the project's inception, specified with 4 digits.
+            This value is used when generating copyright notices as well as being informational.
           ]]></description>
           <type>String</type>
         </field>
@@ -274,9 +253,7 @@
           <name>gumpRepositoryId</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Optional. This is the Id of the Gump repository that this project is
-            part of (assuming it participates in the Gump integration
-            effort).
+            This is the repository identifier in Gump that this project is part of.
           ]]></description>
           <type>String</type>
         </field>
@@ -284,9 +261,8 @@
           <name>siteAddress</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Optional. The hostname of the web server that hosts the project's web
-            site.  This is used when the web site is 
-            <a href="/plugins/site/index.html">deployed</a>.
+            The hostname of the web server that hosts the project's web site. This is used when the web site is
+             deployed.
           ]]></description>
           <type>String</type>
         </field>
@@ -294,9 +270,8 @@
           <name>siteDirectory</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Optional. The directory on the web server where the public web site
-            for this project resides.  This is used when the web site is 
-            <a href="/plugins/site/index.html">deployed</a>.
+            The directory on the web server where the public web site
+            for this project resides.  This is used when the web site is deployed.
           ]]></description>
           <type>String</type>
         </field>
@@ -304,38 +279,26 @@
           <name>distributionSite</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Optional. The server server where the final
-            distributions will be published.  This is used when the
-            distributions are
-            <a href="/plugins/dist/index.html">deployed</a>.
-            <p>
-              If this isn't defined, the central repository is used instead as
-              determined by <code>maven.repo.central</code> and 
-              <code>maven.repo.central.directory</code>
-            </p>
+            The server where the final distributions will be published.  This is used when the
+            distributions are deployed. If this isn't defined, the central repository is used instead as
+              determined by <code>maven.repo.central</code> and <code>maven.repo.central.directory</code>.
           ]]></description>
           <type>String</type>
-          <comment>This naming is inconsistent and distribution should occur from a repository structure.</comment>
         </field>
         <field>
           <name>distributionDirectory</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Optional. The directory on the web server where the final
-            distributions will be published.  This is used when the
-            distributions are
-            <a href="/plugins/dist/index.html">deployed</a>.
+            The directory on the web server where the final distributions will be published.  This is used when the
+            distributions are deployed.
           ]]></description>
           <type>String</type>
-          <comment>This naming is inconsistent and distribution should occur from a repository structure.</comment>
         </field>
         <field>
           <name>mailingLists</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            Contains information about a project's mailing lists.  This
-            is used to generate the <a href="/plugins/site/index.html">front
-            page</a> of the site's web site.
+            Contains information about a project's mailing lists.
           ]]></description>
           <association>
             <type>MailingList</type>
@@ -346,9 +309,7 @@
           <name>developers</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            Describes the committers to a project.  This is used to
-            generate the <a href="/plugins/site/index.html">Project Team</a>
-            page of the project's web site.
+            Describes the committers of a project.
           ]]></description>
           <association>
             <type>Developer</type>
@@ -359,9 +320,7 @@
           <name>contributors</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            Describes the contributors to a project.  This is used to generate
-            the <a href="/plugins/site/index.html">Project Team</a> page of
-            the project's web site.
+            Describes the contributors to a project that are not yet committers.
           ]]></description>
           <association>
             <type>Contributor</type>
@@ -374,10 +333,11 @@
           <description><![CDATA[
             This element describes all of the licenses for this project.  
             Each license is described by a <code>license</code> element, which 
-            is then described by additional elements (described below).  The 
-            auto-generated site documentation references this information.  
+            is then described by additional elements.
             Projects should only list the license(s) that applies to the project 
             and not the licenses that apply to dependencies.
+            If multiple licenses are listed, it is assumed that the user can select any of them, not that they
+            must accept all.
           ]]></description>
           <association>
             <type>License</type>
@@ -388,10 +348,7 @@
           <name>versions</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Optional. Contains information on previous versions of the
-            project. This information is used when invoking the 
-            <a href="/plugins/dist/index.html"><code>maven:dist</code></a>
-            target.
+            Contains information on previous versions of the project.
           ]]></description>
           <association>
             <type>Version</type>
@@ -402,10 +359,7 @@
           <name>branches</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Optional. Contains information on branches of the
-            project. This information is used when invoking the 
-            <a href="/plugins/dist/index.html"><code>maven:dist</code></a>
-            target.
+            Contains information on SCM branches of the project.
           ]]></description>
           <association>
             <type>Branch</type>
@@ -439,7 +393,8 @@
         <field>
           <name>scm</name>
           <version>4.0.0</version>
-          <description><![CDATA[Specification for the SCM used by the project.]]></description>
+          <description>
+            <![CDATA[Specification for the SCM used by the project, such as CVS, Subversion, etc.]]></description>
           <association>
             <type>Scm</type>
           </association>
@@ -447,12 +402,11 @@
         <field>
           <name>repository</name>
           <version>3.0.0</version>
-          <description><![CDATA[Specification for the SCM used by the project.]]></description>
+          <description>
+            <![CDATA[Specification for the SCM used by the project, such as CVS, Subversion, etc.]]></description>
           <association>
             <type>Repository</type>
           </association>
-          <comment>This element needs to be renamed as it conflicts with the existing notion of repositories in
-            Maven.</comment>
         </field>
         <field>
           <name>organization</name>
@@ -471,7 +425,7 @@
           <name>properties</name>
           <version>3.0.0</version>
           <description><![CDATA[
-             Project properties that will be used by various plugins
+             Project properties that will be used by various plugins. The format is <code>&lt;name&gt;value&lt;/name&gt;</code>.
           ]]></description>
           <type>Properties</type>
           <association xml.mapStyle="inline">
@@ -485,7 +439,7 @@
           <type>String</type>
           <description><![CDATA[
             The Java package name of the project.  This value is used
-            when generating <a href="/plugins/javadoc/index.html">JavaDoc</a>.
+            when generating JavaDoc.
           ]]></description>
         </field>
         <field>
@@ -501,7 +455,7 @@
           <name>profiles</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            Listing of project-local build profiles which will modify the build process when activated.
+            A listing of project-local build profiles which will modify the build process when activated.
           ]]></description>
           <association>
             <type>Profile</type>
@@ -513,7 +467,6 @@
         <codeSegment>
           <version>3.0.0</version>
           <code><![CDATA[
-          
               public void setVersion(String version)
               {
                   this.currentVersion = version;
@@ -564,7 +517,10 @@
         <field>
           <name>modules</name>
           <version>4.0.0</version>
-          <description>The modules to build in addition to the current project</description>
+          <description>
+            The modules (sometimes called subprojects) to build as a part of this project.
+            Each module listed is a relative path to the directory containing the module.
+          </description>
           <association>
             <type>String</type>
             <multiplicity>*</multiplicity>
@@ -573,7 +529,8 @@
         <field>
           <name>repositories</name>
           <version>4.0.0</version>
-          <description><![CDATA[The lists of the remote repositories]]></description>
+          <description><![CDATA[The lists of the remote repositories for discovering dependencies and
+          extensions.]]></description>
           <association>
             <type>Repository</type>
             <multiplicity>*</multiplicity>
@@ -582,81 +539,35 @@
         <field>
           <name>pluginRepositories</name>
           <version>4.0.0</version>
-          <description><![CDATA[The lists of the remote repositories for discovering plugins]]></description>
+          <description>
+            <![CDATA[The lists of the remote repositories for discovering plugins for builds and reports.]]></description>
           <association>
             <type>Repository</type>
             <multiplicity>*</multiplicity>
           </association>
-          <comment>This may be removed or relocated in the near future. It is undecided whether plugins really need a
-            remote repository set of their own.</comment>
         </field>
         <field>
           <name>dependencies</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            <p>
               This element describes all of the dependencies associated with a
-              project.  Each dependency is described by a
-              <code>dependency</code> element, which is then described by
-              additional elements (described below).
-            </p>
-            <p>
+              project.
               These dependencies are used to construct a classpath for your 
-              project during the build process.
-            </p>
-            <p>
-              Maven can automatically download these dependencies from a 
-              <a href="/user-guide.html#Remote%20Repository%20Layout">remote repository</a>.
-            </p>
-            <p>
-              The filename that Maven downloads from the repository is 
-              <code>artifactId-version.jar</code> where <code>artifactId</code> 
-              corresponds to the <code>artifactId</code> element and 
-              <code>version</code> corresponds to the <code>version</code> element.
-            </p>
-            <p>
-              When Maven goes looking for a dependency in the remote repository, 
-              it uses the dependency element to construct the URL to download 
-              from. This URL is defined as:
-            </p>
-            <div class="source">
-              <pre>${repo}/${groupId}/${type}s/${artifactId}-${version}.${type}</pre>
-            </div>
-            <p>
-              Where
-            </p>
-            <dl>
-              <dt>repo</dt>
-              <dd>
-                is the remote repository URL specified by 
-                <code>${maven.repo.remote}</code>
-              </dd>
-              
-              <dt>groupId</dt>
-              <dd>is taken from the dependency element</dd>
-              
-              <dt>type</dt>
-              <dd>is taken from the dependency element</dd>
-              
-              <dt>artifactId</dt>
-              <dd>is taken from the dependency element</dd>
-              
-              <dt>version</dt>
-              <dd>is taken from the dependency element</dd>
-            </dl>
+              project during the build process. They are automatically downloaded from the
+              repositories defined in this project.
+              See <a href="http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html">the
+              dependency mechanism</a> for more information.
           ]]></description>
           <association>
             <type>Dependency</type>
             <multiplicity>*</multiplicity>
           </association>
-          <comment>These should ultimately only be compile time dependencies when transitive dependencies come into
-            play.</comment>
         </field>
         <field>
           <name>reports</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            NOT A VALID ELEMENT. LISTED TO ALLOW LEGACY REPOSITORY POMs TO PARSE.
+            <b>Deprecated</b>. Now ignored by Maven.
           ]]></description>
           <type>DOM</type>
         </field>
@@ -664,11 +575,9 @@
           <name>reporting</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            This element includes the specification of reports to be
-            included in a Maven-generated site.  These reports will be run
-            when a user executes <code>maven site</code>.  All of the
-            reports will be included in the navigation bar for browsing in
-            the order they are specified.
+            This element includes the specification of report plugins to use to generate the reports on the
+            Maven-generated site.  These reports will be run when a user executes <code>mvn site</code>.  All of the
+            reports will be included in the navigation bar for browsing.
           ]]></description>
           <association>
             <type>Reporting</type>
@@ -679,13 +588,11 @@
           <version>4.0.0</version>
           <required>false</required>
           <description><![CDATA[
-            Default dependency information for grouped projects inheriting from 
-            this one. The dependency information here will not be checked.
+            Default dependency information for projects that inherit from
+            this one. The dependencies in this section are not immediately resolved.
             Instead, when a POM derived from this one declares a dependency 
-            described by a groupId and an artifactId (version not necessary), 
-            the entries in here will supply default values for that dependency.
-            Any locally-supplied information for a particular dependency will
-            overwrite any information specified here for that project.
+            described by a matching groupId and artifactId, the version and other values from this
+            section are used for that dependency if they were not already specified.
           ]]></description>
           <association>
             <type>DependencyManagement</type>
@@ -694,7 +601,8 @@
         <field>
           <name>distributionManagement</name>
           <version>4.0.0</version>
-          <description><![CDATA[Distribution information for a project.]]></description>
+          <description><![CDATA[Distribution information for a project that enables deployment of the site
+          and artifacts to remote web servers and repositories respectively.]]></description>
           <association>
             <type>DistributionManagement</type>
           </association>
@@ -703,7 +611,8 @@
           <name>properties</name>
           <version>4.0.0</version>
           <description><![CDATA[
-             Properties used to fill in plugin configuration
+             Properties that can be used throughout the POM as a substitution, and are used as filters in resources
+             if enabled. The format is <code>&lt;name&gt;value&lt;/name&gt;</code>.
           ]]></description>
           <type>Properties</type>
           <association xml.mapStyle="inline">
@@ -713,14 +622,11 @@
         </field>
       </fields>
     </class>
-    <!-- @todo: is any of this too CVS specific? Investigate other SCMs -->
     <class>
       <name>Branch</name>
       <version>3.0.0</version>
       <description><![CDATA[
-       Optional. Contains information on branches of the project. This  
-       information is used when invoking the 
-       <a href="/plugins/dist/index.html"><code>maven:dist</code></a> target.
+       Contains information on the SCM branches of the project.
       ]]></description>
       <fields>
         <field>
@@ -744,10 +650,7 @@
           <name>plugins</name>
           <version>4.0.0</version>
           <description>
-            The plugins specified here are not validated until they
-            are referenced in a POM within the group. This allows the
-            specification of a "standard" version for a particular
-            plugin.
+            The list of plugins to use.
           </description>
           <association>
             <type>Plugin</type>
@@ -800,7 +703,7 @@
           <description><![CDATA[
             Default plugin information to be made available for reference by 
             projects derived from this one. This plugin configuration will not
-            be validated or bound to the lifecycle unless referenced. Any local
+            be resolved or bound to the lifecycle unless referenced. Any local
             configuration for a given plugin will override the plugin's entire
             definition here.
           ]]></description>
@@ -827,11 +730,8 @@
           <name>resources</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            This element describes all of the resources associated with a 
-            project or unit tests. Each resource is described by a resource 
-            element, which is then described by additional elements (described 
-            <a href="#resource">below</a>). These resources are used to complete 
-            the jar file or to run unit test.
+            This element describes all of the classpath resources such as properties files associated with a
+            project. These resources are often included in the final package.
           ]]></description>
           <association>
             <type>Resource</type>
@@ -842,11 +742,8 @@
           <name>testResources</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            This element describes all of the resources associated with a 
-            project's unit tests. Each resource is described by a resource 
-            element, which is then described by additional elements (described
-            <a href="#resource">below</a>). These resources are used to complete 
-            the jar file or to run unit test.
+            This element describes all of the classpath resources such as properties files associated with a
+            project's unit tests.
           ]]></description>
           <association>
             <type>Resource</type>
@@ -857,7 +754,7 @@
           <name>directory</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            The directory where all files generated by the build is placed.
+            The directory where all files generated by the build are placed.
           ]]></description>
           <type>String</type>
         </field>
@@ -866,7 +763,7 @@
           <version>4.0.0</version>
           <description><![CDATA[
             The filename (excluding the extension, and with no path information) that the produced artifact
-            will be called. The default value is artifactId-version.
+            will be called. The default value is <code>${artifactId}-${version}</code>.
           ]]></description>
           <type>String</type>
         </field>
@@ -895,9 +792,7 @@
             An address to which notifications regarding the status of builds
             for this project can be sent. This is intended for use by tools
             which do unattended builds, for example those providing for
-            continuous integration. Currently this is used by the
-            <a href="/plugins/gump/">gump plugin</a>
-            target.
+            continuous integration.
           ]]></description>
           <type>String</type>
         </field>
@@ -934,7 +829,6 @@
             This element specifies a directory containing the unit test
             source of the project. The generated build system will
             compile these directories when the project is being tested.
-            The unit tests must use the JUnit test framework.
             The path given is relative to the project descriptor.
           ]]></description>
           <type>String</type>
@@ -947,7 +841,6 @@
             This element specifies a directory containing the unit test
             source of the project. The generated build system will
             compile these directories when the project is being tested.
-            The unit tests must use the JUnit test framework.
             The path given is relative to the project descriptor.
           ]]></description>
           <type>String</type>
@@ -959,9 +852,7 @@
              This element specifies a directory containing Aspect    
              sources of the project.  The generated build system will    
              compile the Aspects in this directory when the project is    
-             built if Aspects have been enabled (see the    
-             <a    
-               href="/plugins/aspectj/goals.html">Aspectj goals</a> document).    
+             built if Aspects have been enabled.
              The path given is relative to the project descriptor.    
            ]]></description>
           <type>String</type>
@@ -971,7 +862,7 @@
           <version>3.0.0</version>
           <description><![CDATA[    
              This element specifies a directory containing integration test    
-             sources of the project.    
+             sources of the project. This element is not known to be used.
            ]]></description>
           <type>String</type>
         </field>
@@ -981,9 +872,7 @@
           <required>true</required>
           <description><![CDATA[
             This element describes all of the sourceModifications associated 
-            with a project.  Each source modification is described by a
-            <code>sourceModification</code> element, which is then described by
-             additional elements (described below).  These modifications are used 
+            with a project. These modifications are used
             to exclude or include various source depending on the environment
              the build is running in.
           ]]></description>
@@ -1038,13 +927,15 @@
         <field>
           <name>system</name>
           <version>4.0.0</version>
-          <description><![CDATA[The name of the continuous integration system i.e. Bugzilla]]></description>
+          <description>
+            <![CDATA[The name of the continuous integration system, e.g. <code>continuum</code>.]]></description>
           <type>String</type>
         </field>
         <field>
           <name>url</name>
           <version>4.0.0</version>
-          <description><![CDATA[Url for the continuous integration system used by the project.]]></description>
+          <description>
+            <![CDATA[URL for the continuous integration system used by the project if it has a web interface.]]></description>
           <type>String</type>
         </field>
         <field>
@@ -1080,37 +971,37 @@
           <version>4.0.0</version>
           <defaultValue>true</defaultValue>
           <type>boolean</type>
-          <description>Send notification on error.</description>
+          <description>Whether to send notifications on error.</description>
         </field>
         <field>
           <name>sendOnFailure</name>
           <version>4.0.0</version>
           <defaultValue>true</defaultValue>
           <type>boolean</type>
-          <description>Send notification on failure.</description>
+          <description>Whether to send notifications on failure.</description>
         </field>
         <field>
           <name>sendOnSuccess</name>
           <version>4.0.0</version>
           <defaultValue>true</defaultValue>
           <type>boolean</type>
-          <description>Send notification on success.</description>
+          <description>Whether to send notifications on success.</description>
         </field>
         <field>
           <name>sendOnWarning</name>
           <version>4.0.0</version>
           <defaultValue>true</defaultValue>
           <type>boolean</type>
-          <description>Send notification on warning.</description>
+          <description>Whether to send notifications on warning.</description>
         </field>
         <!-- TODO: Remove it after continuum alpha-3 release -->
         <field>
           <name>address</name>
           <version>4.0.0</version>
           <type>String</type>
-          <description>
-            Where to send the notification to - eg email address. DEPRECATED.
-          </description>
+          <description><![CDATA[
+            <b>Deprecated</b>. Where to send the notification to - eg email address.
+          ]]></description>
         </field>
         <field>
           <name>configuration</name>
@@ -1171,7 +1062,7 @@
           <description><![CDATA[
             The roles the contributor plays in the project.  Each role is
             described by a <code>role</code> element, the body of which is a
-            role name.
+            role name. This can also be used to describe the contribution.
           ]]></description>
           <association>
             <type>String</type>
@@ -1209,12 +1100,8 @@
           <version>3.0.0</version>
           <required>true</required>
           <description><![CDATA[
-            <p>The name of the dependency.</p>
-            <p>
-              <strong>Note:</strong> The use of the id element for
-              a dependency is deprecated. Please use <code>groupId</code> and
+              <strong>Deprecated</strong>. Please use <code>groupId</code> and
               <code>artifactId</code> together instead.
-            </p>
           ]]></description>
           <type>String</type>
         </field>
@@ -1224,7 +1111,7 @@
           <required>true</required>
           <description><![CDATA[
             The project group that produced the dependency, e.g.
-            <code>geronimo</code>.
+            <code>org.apache.maven</code>.
           ]]></description>
           <type>String</type>
         </field>
@@ -1234,7 +1121,7 @@
           <required>true</required>
           <description><![CDATA[
             The unique id for an artifact produced by the project group, e.g.
-            <code>germonimo-jms</code>
+            <code>maven-artifact</code>.
           ]]></description>
           <type>String</type>
         </field>
@@ -1242,7 +1129,8 @@
           <name>version</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            The version of the dependency, e.g. <code>3.2.1</code>
+            The version of the dependency, e.g. <code>3.2.1</code>. In Maven 2, this can also be
+            specified as a range of versions.
           ]]></description>
           <type>String</type>
         </field>
@@ -1254,27 +1142,39 @@
             from the central repository.
           ]]></description>
           <type>String</type>
-          <comment>The URL should really be gleaned from a shared database of dependency information.</comment>
         </field>
         <field>
           <name>jar</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Literal name of the artifact. Used to override the calculated artifact name.
+            Literal name of the artifact in the repository. Used to override the calculated artifact name.
           ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>type</name>
-          <version>3.0.0+</version>
+          <version>3.0.0</version>
+          <description><![CDATA[
+            The type of dependency. This defaults to <code>jar</code>. While it usually represents the extension on
+            the filename of the dependency, that is not always the case.
+            Some examples are <code>jar</code>, <code>war</code>, and <code>plugin</code>.
+            A dependency of type <code>plugin</code> is loaded as a Maven plugin and not added to the project
+            build classpath.
+          ]]></description>
+          <type>String</type>
+          <defaultValue>jar</defaultValue>
+        </field>
+        <field>
+          <name>type</name>
+          <version>4.0.0</version>
           <description><![CDATA[
-            The type of dependency. This defaults to <code>jar</code>.
-            Known recognised dependency types are:
-            <ul>
-            <li><code>jar</code></li>
-            <li><code>ejb</code></li>
-            <li><code>plugin</code></li>
-            </ul>
+            The type of dependency. This defaults to <code>jar</code>. While it usually represents the extension on
+            the filename of the dependency, that is not always the case. A type can be mapped to a different
+            extension and a classifier.
+            The type often correspongs to the packaging used, though this is also not always the case.
+            Some examples are <code>jar</code>, <code>war</code>, <code>ejb-client</code> and <code>test-jar</code>.
+            New types can be defined by plugins that set
+            <code>extensions</code> to <code>true</code>, so this is not a complete list.
           ]]></description>
           <type>String</type>
           <defaultValue>jar</defaultValue>
@@ -1282,10 +1182,11 @@
         <field>
           <name>classifier</name>
           <version>4.0.0</version>
-          <description>
+          <description><![CDATA[
             The classifier of the dependency. This allows distinguishing two artifacts that belong to the same POM but
-            were built differently, and is appended to the filename after the version.
-          </description>
+            were built differently, and is appended to the filename after the version. For example,
+            <code>jdk14</code> and <code>jdk15</code>.
+          ]]></description>
           <type>String</type>
           <required>false</required>
         </field>
@@ -1294,11 +1195,9 @@
           <version>3.0.0</version>
           <description><![CDATA[
             Properties about the dependency. Various plugins allow you to 
-            <code>mark</code> dependencies with properties. For example the 
-            <a href="/plugins/war/index.html">war</a> plugin looks for a 
+            mark dependencies with properties. For example the war plugin looks for a
             <code>war.bundle</code> property, and if found will include the 
-            dependency in <code>WEB-INF/lib</code>. For example syntax, check 
-            the war plugin docs.
+            dependency in <code>WEB-INF/lib</code>.
           ]]></description>
           <type>Properties</type>
           <association xml.mapStyle="inline">
@@ -1310,11 +1209,12 @@
           <name>scope</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            The scope of the dependency - compile, runtime, test, system. Used to
-            calculate the various classpaths used for testing, etc. and for 
-            determining which artifacts to include in a distribution of this
-            project. For more information, see 
-            <a href="http://maven.apache.org/maven2/dependency-mechanism.html">Dependency Mechanism</a>.]]>
+            The scope of the dependency - <code>compile</code>, <code>runtime</code>, <code>test</code>,
+            <code>system</code>, and <code>provided</code>. Used to
+            calculate the various classpaths used for compilation, testing, and so on. It also assists in determining
+            which artifacts to include in a distribution of this project. For more information, see
+            <a href="http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html">the
+            dependency mechanism</a>.]]>
           </description>
           <type>String</type>
           <!-- This default has to be enforced at the maven-artifact layer, to allow 
@@ -1326,13 +1226,13 @@
         <field>
           <name>systemPath</name>
           <version>4.0.0</version>
-          <description>
-            FOR SYSTEM SCOPE ONLY.
-            This specifies the path on the filesystem for this dependency.
+          <description><![CDATA[
+            FOR SYSTEM SCOPE ONLY. Note that use of this property is <b>discouraged</b> and may be replaced in later
+            versions. This specifies the path on the filesystem for this dependency.
             Requires an absolute path for the value, not relative.
             Use a property that gives the machine specific absolute path,
-            e.g. ${java.home}.
-          </description>
+            e.g. <code>${java.home}</code>.
+          ]]></description>
           <type>String</type>
         </field>
         <field>
@@ -1480,15 +1380,14 @@
       <superClass>Contributor</superClass>
       <name>Developer</name>
       <description><![CDATA[
-        Information about one of the committers on this project. Derived from
-        <code>Contributor</code>.
+        Information about one of the committers on this project.
       ]]></description>
       <version>3.0.0+</version>
       <fields>
         <field>
           <name>id</name>
           <version>3.0.0+</version>
-          <description><![CDATA[The username of the developer.]]></description>
+          <description><![CDATA[The unique ID of the developer in the SCM.]]></description>
           <type>String</type>
         </field>
       </fields>
@@ -1500,14 +1399,14 @@
         <field>
           <name>artifactId</name>
           <version>4.0.0</version>
-          <description><![CDATA[The artifact id of the project to exclude.]]></description>
+          <description><![CDATA[The artifact ID of the project to exclude.]]></description>
           <type>String</type>
           <required>true</required>
         </field>
         <field>
           <name>groupId</name>
           <version>4.0.0</version>
-          <description><![CDATA[The group id of the project to exclude.]]></description>
+          <description><![CDATA[The group ID of the project to exclude.]]></description>
           <type>String</type>
           <required>true</required>
         </field>
@@ -1516,20 +1415,20 @@
     <class>
       <name>IssueManagement</name>
       <description>
-        Information about the bugtracking system used to manage this project.
+        Information about the issue tracking (or bug tracking) system used to manage this project.
       </description>
       <version>4.0.0</version>
       <fields>
         <field>
           <name>system</name>
           <version>4.0.0</version>
-          <description><![CDATA[The name of the issue management system i.e. Bugzilla]]></description>
+          <description><![CDATA[The name of the issue management system, e.g. Bugzilla]]></description>
           <type>String</type>
         </field>
         <field>
           <name>url</name>
           <version>4.0.0</version>
-          <description><![CDATA[Url for the issue management system used by the project.]]></description>
+          <description><![CDATA[URL for the issue management system used by the project.]]></description>
           <type>String</type>
         </field>
       </fields>
@@ -1539,7 +1438,7 @@
       <version>4.0.0</version>
       <description><![CDATA[
         This elements describes all that pertains to distribution for a project.
-        It is primarily used for deployment of artifacts and distributions 
+        It is primarily used for deployment of artifacts and the site
         produced by the build.
       ]]></description>
       <fields>
@@ -1547,8 +1446,7 @@
           <name>repository</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            Information needed for deploying to remote repository artifacts
-            generated by the project
+            Information needed to deploy the artifacts generated by the project to a remote repository.
           ]]></description>
           <association>
             <type>DeploymentRepository</type>
@@ -1557,9 +1455,9 @@
         <field>
           <name>snapshotRepository</name>
           <version>4.0.0</version>
-          <description>
-            Where to deploy snapshots of artifacts to. If not given, it defaults to the repository.
-          </description>
+          <description><![CDATA[
+            Where to deploy snapshots of artifacts to. If not given, it defaults to the <code>repository</code> element.
+          ]]></description>
           <association>
             <type>DeploymentRepository</type>
           </association>
@@ -1567,7 +1465,7 @@
         <field>
           <name>site</name>
           <description><![CDATA[
-            Information needed for deploying website files of the project.
+            Information needed for deploying the web site of the project.
           ]]></description>
           <version>4.0.0</version>
           <association>
@@ -1579,14 +1477,17 @@
           <version>4.0.0+</version>
           <description><![CDATA[
             The URL of the project's download page. If not given users will be referred to the homepage given by
-            <code>url</code>.
+            <code>url</code>. This is given to assist in locating artifacts that are not in the repository due to
+            licensing restrictions.
           ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>relocation</name>
           <version>4.0.0</version>
-          <description>Relocation information if the artifact has been moved to a new group/artifactId</description>
+          <description>
+            Relocation information of the artifact if it has been moved to a new group ID and/or artifact ID.
+          </description>
           <association>
             <type>Relocation</type>
           </association>
@@ -1594,13 +1495,13 @@
         <field>
           <name>status</name>
           <version>4.0.0</version>
-          <description>
+          <description><![CDATA[
             Gives the status of this artifact in the remote repository. This must not be set in your local
-            project, as it is updated by tools placing it in the reposiory. Valid values are: none (default),
-            converted (repository manager converted this from an Maven 1 POM), partner (directly synced from a partner
-            Maven 2 repository), deployed (was deployed from a Maven 2 instance), verified (has been hand verified as
-            correct and final).
-          </description>
+            project, as it is updated by tools placing it in the reposiory. Valid values are: <code>none</code> (default),
+            <code>converted</code> (repository manager converted this from an Maven 1 POM), <code>partner</code>
+            (directly synced from a partner Maven 2 repository), <code>deployed</code> (was deployed from a Maven 2
+            instance), <code>verified</code> (has been hand verified as correct and final).
+          ]]></description>
           <required>false</required>
           <type>String</type>
         </field>
@@ -1610,9 +1511,8 @@
       <name>License</name>
       <description><![CDATA[
         Describes the licenses for this project.  This is used to generate
-        the <a href="/plugins/site/index.html">License</a> page of
-        the project's web site. Typically the licenses listed for the project
-        are that of the project itself, and not of dependencies.
+        the license page of the project's web site, as well as being taken into consideration in other reporting and
+        validation. The licenses listed for the project are that of the project itself, and not of dependencies.
       ]]></description>
       <version>3.0.0+</version>
       <fields>
@@ -1657,10 +1557,7 @@
       <version>3.0.0+</version>
       <description><![CDATA[
         This element describes all of the mailing lists associated with
-        a project.  Each mailing list is described by a
-        <code>mailingList</code> element, which is then described by
-        additional elements (described below).  The auto-generated site
-        documentation references this information.
+        a project. The auto-generated site references this information.
       ]]></description>
       <fields>
         <field>
@@ -1714,7 +1611,7 @@
           <name>otherArchives</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            The link to other URLs where you can browse the list archive.
+            The link to alternate URLs where you can browse the list archive.
           ]]></description>
           <association>
             <type>String</type>
@@ -1731,7 +1628,7 @@
     </class>
     <class>
       <name>Organization</name>
-      <description>Specifies the organization who produces this project.</description>
+      <description>Specifies the organization that produces this project.</description>
       <version>3.0.0+</version>
       <fields>
         <field>
@@ -1763,17 +1660,18 @@
     <class>
       <name>PackageGroup</name>
       <version>3.0.0</version>
+      <description>A JavaDoc package group.</description>
       <fields>
         <field>
           <name>title</name>
           <version>3.0.0</version>
-          <description><![CDATA[the description]]></description>
+          <description><![CDATA[The title to use for the package group.]]></description>
           <type>String</type>
         </field>
         <field>
           <name>packages</name>
           <version>3.0.0</version>
-          <description><![CDATA[the description]]></description>
+          <description><![CDATA[The packages in the group]]></description>
           <type>String</type>
         </field>
       </fields>
@@ -1785,7 +1683,7 @@
         <field>
           <name>includes</name>
           <version>3.0.0+</version>
-          <description><![CDATA[the description]]></description>
+          <description><![CDATA[A list of patterns to include, e.g. <code>**&#47;*.xml</code>.]]></description>
           <association>
             <type>String</type>
             <multiplicity>*</multiplicity>
@@ -1794,7 +1692,7 @@
         <field>
           <name>excludes</name>
           <version>3.0.0+</version>
-          <description><![CDATA[the description]]></description>
+          <description><![CDATA[A list of patterns to exclude, e.g. <code>**&#47;*.xml</code>]]></description>
           <association>
             <type>String</type>
             <multiplicity>*</multiplicity>
@@ -1809,43 +1707,36 @@
         <field>
           <name>artifactId</name>
           <version>4.0.0</version>
-          <description><![CDATA[The artifact id of the project to extend.]]></description>
+          <description><![CDATA[The artifact id of the parent project to inherit from.]]></description>
           <required>true</required>
           <type>String</type>
         </field>
         <field>
           <name>groupId</name>
           <version>4.0.0</version>
-          <description><![CDATA[The group id of the project to extend.]]></description>
+          <description><![CDATA[The group id of the parent project to inherit from.]]></description>
           <required>true</required>
           <type>String</type>
         </field>
         <field>
           <name>version</name>
           <version>4.0.0</version>
-          <description><![CDATA[The version of the project to extend.]]></description>
+          <description><![CDATA[The version of the parent project to inherit.]]></description>
           <type>String</type>
         </field>
         <field>
           <name>relativePath</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            The relative path of the parent-pom within the project hierarchy.
-            The default value is ../pom.xml.
-            <p>
-            Normally, Maven looks for the parent pom first in the default location,
-            then the local repository, and lastly in the remote repo.
-            </p>
-            <p>
-            relativePath allows you to select a different location,
+            The relative path of the parent <code>pom.xml</code> file within the check out.
+            The default value is <code>../pom.xml</code>.
+            Maven looks for the parent pom first in the reactor of currently building projects, then in this location on
+            the filesystem, then the local repository, and lastly in the remote repo.
+            <code>relativePath</code> allows you to select a different location,
             for example when your structure is flat, or deeper without an intermediate parent pom.
-            </p>
-            <p>
-            However, the group and artifact ID is still required,
-            as when the parent is coming from the repository,
-            it must look for the parent in the repository, and so on.
+            However, the group ID, artifact ID and version are still required,
+            and must match the file in the location given or it will revert to the repository for the POM.
             This feature is only for enhancing the development in a local checkout of that project.
-            </p>
           ]]></description>
           <type>String</type>
           <defaultValue>../pom.xml</defaultValue>
@@ -1882,87 +1773,12 @@
           <name>connection</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            <p>
-              Optional.  The source configuration management system URL
+              The source control management system URL
               that describes the repository and how to connect to the
-              repository.  This is used by Maven when <a href="/plugins/dist/index.html">building versions</a>
-              from specific ID.
-            </p>
-            <p>
-              The format of this element is as follows:
-            </p>
-            <pre>scm:&lt;provider&gt;:&lt;provider-parameters&gt;</pre>
-            <p>For cvs, the format for pserver repositories should be:</p>
-            <div class="source">
-              <pre>scm:cvs:pserver:user@host:/cvs/root:module-name</pre>
-            </div>
-            <p>
-              For local networked repositories (eg. pserver to local machine)
-            </p>
-            <div class="source">
-              <pre>scm:cvs:lserver:user@host:/cvs/root:module-name</pre>
-            </div>
-            <p>
-              For ssh access:
-            </p>
-            <div class="source">
-              <pre>scm:cvs:ext:user@host:/cvs/root:module-name</pre>
-            </div>
-
-            Remember that CVS will expect an environment variable called
-            <code>CVS_RSH</code> to be set, typically to <code>ssh</code> or your
-            ssh client.
-            
-            <p>
-              Some cvs clients support other protocols, such as ntserver and extssh.
-              Here's an example using CVS NT and ntserver:
-            </p>
-            <div class="source">
-              <pre>scm|cvs|ntserver|user@server|e:\cvs|Deployment</pre>
-            </div>
-  
-            Note the use of the vertical bar as delimiter as the repository has a 
-            colon (<code>:</code>) in it.
-            
-            <p>
-              For local file system repositories
-            </p>
-            <div class="source">
-              <pre>scm:cvs:local:ignored:/cvs/root:module-name</pre>
-            </div>
-  
-            <p>
-              For StarTeam access: 
-            </p>
-            <div class="source">
-              <pre>scm:starteam:username:password@host:port/project/view/folder</pre>
-            </div>
-
-            All of this information can be had from either the StarTeam Universal 
-            Client (Tools-&gt;Server Administration-&gt;Server Properties) or from the 
-            administrator. 
-            
-            <p>
-              The delimiter is determined by the character after "scm". eg.
-              <code>scm|cvs|pserver|user@host|/cvs/root|module-name</code> 
-              is equivalent to that listed above. This can be useful for Windows users
-              who have : in their cvsroot parameter (eg. D:\cvsroot)
-            </p>
-            <p>
-              Where <code>pserver</code> is the protocol used to access CVS,
-              <code>user@host</code> is the user name to log in to the specified
-              cvs <strong>host</strong>, <code>/cvs/root</code> is the cvs root
-              directory, and <code>module-name</code> is the name of the cvs
-              module to be worked on
-            </p>
-
-            <p>As an example, the settings for an Apache project are usually:</p>
-            <pre>scm:cvs:pserver:anoncvs@cvs.apache.org:/home/cvspublic:module-name</pre>
-            
-            <p>
-              Currently CVS, Starteam and  SubVersion are the only supported scm's.
-              Others will be added as soon as possible
-            </p>
+              repository. For more information, see the
+              <a href="http://maven.apache.org/scm/scm-url-format.html">URL format</a>
+              and <a href="http://maven.apache.org/scm/scms-overview.html">list of supported SCMs</a>.
+              This connection is read-only.
           ]]></description>
           <type>String</type>
         </field>
@@ -1970,7 +1786,7 @@
           <name>developerConnection</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            Just like connection, but for developers, i.e. this scm connection
+            Just like <code>connection</code>, but for developers, i.e. this scm connection
             will not be read only.
           ]]></description>
           <type>String</type>
@@ -1978,7 +1794,8 @@
         <field>
           <name>url</name>
           <version>3.0.0</version>
-          <description><![CDATA[The URL to the project's browsable CVS repository.]]></description>
+          <description>
+            <![CDATA[The URL to the project's browsable SCM repository, such as ViewVC or Fisheye.]]></description>
           <type>String</type>
         </field>
       </fields>
@@ -1991,11 +1808,12 @@
           <name>connection</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            The <a href="http://maven.apache.org/scm/scm-url-format.html">source configuration management system URL</a>
-            that describes the repository and how to connect to the
-            repository.  This is used by Maven when
-            <a href="/plugins/maven-assembly-plugin/index.html">building versions</a>
-            from specific ID.
+              The source control management system URL
+              that describes the repository and how to connect to the
+              repository. For more information, see the
+              <a href="http://maven.apache.org/scm/scm-url-format.html">URL format</a>
+              and <a href="http://maven.apache.org/scm/scms-overview.html">list of supported SCMs</a>.
+              This connection is read-only.
           ]]></description>
           <type>String</type>
         </field>
@@ -2003,7 +1821,7 @@
           <name>developerConnection</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            Just like connection, but for developers, i.e. this scm connection
+            Just like <code>connection</code>, but for developers, i.e. this scm connection
             will not be read only.
           ]]></description>
           <type>String</type>
@@ -2020,7 +1838,8 @@
         <field>
           <name>url</name>
           <version>4.0.0</version>
-          <description><![CDATA[The URL to the project's browsable scm repository.]]></description>
+          <description>
+            <![CDATA[The URL to the project's browsable SCM repository, such as ViewVC or Fisheye.]]></description>
           <type>String</type>
         </field>
       </fields>
@@ -2034,8 +1853,8 @@
           <name>directory</name>
           <version>3.0.0+</version>
           <description><![CDATA[
-            Describe the directory where the resource is stored.
-            The path may be absolute, or relative to the project.xml file.
+            Describe the directory where the resources are stored.
+            The path is relative to the POM.
           ]]></description>
           <type>String</type>
         </field>
@@ -2044,11 +1863,8 @@
     <class>
       <name>Resource</name>
       <description><![CDATA[
-        This element describes all of the resources associated with a project or 
-        unit tests. Each resource is described by a resource element, which is 
-        then described by additional elements (described 
-        <a href="#resource">below</a>). These resources are used to complete the 
-        jar file or to run unit test.
+        This element describes all of the classpath resources associated with a project or
+        unit tests.
       ]]></description>
       <version>3.0.0+</version>
       <superClass>FileSet</superClass>
@@ -2058,16 +1874,21 @@
           <version>3.0.0+</version>
           <description><![CDATA[
             Describe the resource target path. For example, if you want that 
-            resource appear into a specific package 
+            resource to appear in a specific package
             (<code>org.apache.maven.messages</code>), you must specify this 
-            element with this value : <code>org/apache/maven/messages</code>
+            element with this value: <code>org/apache/maven/messages</code>.
+            This is not required if you simply put the resources in that directory structure at the source, however.
           ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>filtering</name>
           <version>3.0.0+</version>
-          <description><![CDATA[Boolean. Describe if resources are filtered or not.]]></description>
+          <description><![CDATA[
+            Whether resources are filtered to replace tokens with parameterised values or not.
+            The values are taken from the <code>properties</code> element and from the properties in the files listed
+            in the <code>filters</code> element.
+          ]]></description>
           <type>boolean</type>
           <defaultValue>false</defaultValue>
         </field>
@@ -2076,10 +1897,8 @@
     <class>
       <name>SourceModification</name>
       <description><![CDATA[
-        This element describes all of the sourceModifications associated with a
-        project.  Each source modification is described by a
-        <code>sourceModification</code> element, which is then described by
-        additional elements (described below).  These modifications are used 
+        This element describes all of the source modifications associated with a
+        project. These modifications are used
         to exclude or include various source depending on the environment
         the build is running in.
       ]]></description>
@@ -2092,15 +1911,18 @@
           <description><![CDATA[
             If the class with this name can <strong>not</strong> be
             loaded, then the includes and excludes specified below 
-            will be applied to the contents of the 
-            <a href="#sourceDirectory">sourceDirectory</a>
+            will be applied to the contents of the <code>sourceDirectory</code>.
           ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>property</name>
           <version>3.0.0</version>
-          <description><![CDATA[the description]]></description>
+          <description><![CDATA[
+            If the property with this name is <strong>not</strong> set,
+            then the includes and excludes specified below
+            will be applied to the contents of the <code>sourceDirectory</code>.
+          ]]></description>
           <type>String</type>
         </field>
       </fields>
@@ -2113,7 +1935,7 @@
         <field>
           <name>resources</name>
           <version>3.0.0</version>
-          <description><![CDATA[the description]]></description>
+          <description><![CDATA[The classpath resources to use when executing the unit tests.]]></description>
           <association>
             <type>Resource</type>
             <multiplicity>*</multiplicity>
@@ -2146,7 +1968,7 @@
           <name>tag</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            The name given in the version control system (e.g. cvs) used by the project for the source
+            The name given in the SCM (e.g. CVS) used by the project for the source
             code associated with this version of the project.
           ]]></description>
           <type>String</type>
@@ -2155,10 +1977,7 @@
           <name>id</name>
           <version>3.0.0</version>
           <description><![CDATA[
-            A unique identifier for a version.  This ID is
-            used to specify the version that
-            <a href="/plugins/dist/index.html">
-              <code>maven:dist</code>
+            A unique identifier for a version. This is usually identical to the name.
             </a> builds.
           ]]></description>
           <type>String</type>
@@ -2181,15 +2000,16 @@
       <name>RepositoryBase</name>
       <version>4.0.0</version>
       <description><![CDATA[
-         Repository contains the information needed
-         for establishing connections with remote repoistory
+         A repository contains the information needed
+         for establishing connections with remote repoistory.
       ]]></description>
       <fields>
         <field>
           <name>id</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            A unique identifier for a repository.
+            A unique identifier for a repository. This is used to match the repository to configuration in
+            the <code>settings.xml</code> file, for example.
           ]]></description>
           <type>String</type>
         </field>
@@ -2197,7 +2017,7 @@
           <name>name</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            Human readable name of the repository
+            Human readable name of the repository.
           ]]></description>
           <type>String</type>
         </field>
@@ -2205,15 +2025,17 @@
           <name>url</name>
           <version>4.0.0</version>
           <description><![CDATA[
-             The url of the repository
+             The url of the repository, in the form <code>protocol://hostname/path</code>.
           ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>layout</name>
           <version>4.0.0</version>
-          <description>The type of layout this repository uses for locating and storing artifacts - can be "legacy" or
-            "default".</description>
+          <description><![CDATA[
+            The type of layout this repository uses for locating and storing artifacts - can be <code>legacy</code> or
+            <code>default</code>.
+          ]]></description>
           <type>String</type>
           <defaultValue>default</defaultValue>
         </field>
@@ -2245,13 +2067,13 @@
       <superClass>RepositoryBase</superClass>
       <version>4.0.0</version>
       <description>
-        Repository contains the information needed for establishing connections with remote repoistory
+        A repository contains the information needed for establishing connections with remote repoistory.
       </description>
       <fields>
         <field>
           <name>releases</name>
           <version>4.0.0</version>
-          <description>How to handle downloading of releases from this repository</description>
+          <description>How to handle downloading of releases from this repository.</description>
           <association>
             <type>RepositoryPolicy</type>
           </association>
@@ -2259,13 +2081,13 @@
         <field>
           <name>snapshots</name>
           <version>4.0.0</version>
-          <description>How to handle downloading of snapshots from this repository</description>
+          <description>How to handle downloading of snapshots from this repository.</description>
           <association>
             <type>RepositoryPolicy</type>
           </association>
         </field>
       </fields>
-      <!-- prevent modello generation of an incorrect equals method. Could be avoided by using <identity/> tags to mark ID as the only identity field -->
+      <!-- TODO:prevent modello generation of an incorrect equals method. Could be avoided by using <identity/> tags to mark ID as the only identity field -->
       <codeSegments>
         <codeSegment>
           <version>4.0.0</version>
@@ -2284,18 +2106,19 @@
       <superClass>RepositoryBase</superClass>
       <version>4.0.0</version>
       <description>
-        Repository contains the information needed for deploying to the remote repoistory
+        Repository contains the information needed for deploying to the remote repoistory.
       </description>
       <fields>
         <field>
           <name>uniqueVersion</name>
-          <description>Whether to assign snapshots a unique version comprised of the timestamp and build number, or to use the same version each time</description>
+          <description>Whether to assign snapshots a unique version comprised of the timestamp and build number, or to
+            use the same version each time</description>
           <type>boolean</type>
           <defaultValue>true</defaultValue>
           <version>4.0.0</version>
         </field>
       </fields>
-      <!-- prevent modello generation of an incorrect equals method. Could be avoided by using <identity/> tags to mark ID as the only identity field -->
+      <!-- TODO:prevent modello generation of an incorrect equals method. Could be avoided by using <identity/> tags to mark ID as the only identity field -->
       <codeSegments>
         <codeSegment>
           <version>4.0.0</version>
@@ -2317,23 +2140,37 @@
         <field>
           <name>enabled</name>
           <version>4.0.0</version>
-          <description>Whether to use this repository for downloading this type of artifact</description>
+          <description>Whether to use this repository for downloading this type of artifact.</description>
           <type>boolean</type>
           <defaultValue>true</defaultValue>
         </field>
         <field>
           <name>updatePolicy</name>
           <version>4.0.0</version>
-          <description>
-            The frequency for downloading updates - can be "always", "daily" (default), "interval:XXX" (in minutes) or
-            "never" (only if it doesn't exist locally).
-          </description>
+          <description><![CDATA[
+            The frequency for downloading updates - can be
+            <code>always,</code>
+            <code>daily</code>
+            (default),
+            <code>interval:XXX</code>
+            (in minutes) or
+            <code>never</code>
+            (only if it doesn't exist locally).
+          ]]></description>
           <type>String</type>
         </field>
         <field>
           <name>checksumPolicy</name>
           <version>4.0.0</version>
-          <description>What to do when verification of an artifact checksum fails. Valid values are "ignore", "fail" or "warn"</description>
+          <description><![CDATA[
+            What to do when verification of an artifact checksum fails. Valid values are
+            <code>ignore</code>
+            ,
+            <code>fail</code>
+            or
+            <code>warn</code>
+            (the default).
+          ]]></description>
           <type>String</type>
         </field>
       </fields>
@@ -2344,15 +2181,15 @@
       <name>Site</name>
       <version>4.0.0</version>
       <description><![CDATA[
-         Site contains the information needed
-         for deploying websites.
+         Contains the information needed for deploying websites.
       ]]></description>
       <fields>
         <field>
           <name>id</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            A unique identifier for a deployment locataion.
+            A unique identifier for a deployment locataion. This is used to match the site to configuration in
+            the <code>settings.xml</code> file, for example.
           ]]></description>
           <type>String</type>
         </field>
@@ -2360,7 +2197,7 @@
           <name>name</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            Human readable name of the deployment location
+            Human readable name of the deployment location.
           ]]></description>
           <type>String</type>
         </field>
@@ -2368,7 +2205,7 @@
           <name>url</name>
           <version>4.0.0</version>
           <description><![CDATA[
-             The url of the location where website is deployed
+             The url of the location where website is deployed, in the form <code>protocol://hostname/path</code>.
           ]]></description>
           <type>String</type>
         </field>
@@ -2383,7 +2220,7 @@
           <name>inherited</name>
           <version>4.0.0</version>
           <description>
-            <![CDATA[Whether this container's configuration should be propagated to child POMs.]]></description>
+            <![CDATA[Whether any configuration should be propagated to child POMs.]]></description>
           <type>String</type>
         </field>
         <field>
@@ -2417,6 +2254,7 @@
       <fields>
         <field>
           <name>groupId</name>
+          <description>The group ID of the plugin in the repository.</description>
           <version>4.0.0</version>
           <type>String</type>
           <required>true</required>
@@ -2424,6 +2262,7 @@
         </field>
         <field>
           <name>artifactId</name>
+          <description>The artifact ID of the plugin in the repository.</description>
           <version>4.0.0</version>
           <type>String</type>
           <required>true</required>
@@ -2432,7 +2271,7 @@
           <name>version</name>
           <version>4.0.0</version>
           <required>true</required>
-          <description><![CDATA[The version of the plugin to be used.]]></description>
+          <description><![CDATA[The version (or valid range of verisons) of the plugin to be used.]]></description>
           <type>String</type>
         </field>
         <field>
@@ -2440,14 +2279,15 @@
           <version>4.0.0</version>
           <type>boolean</type>
           <description>Whether to load Maven extensions (such as packaging and type handlers) from this
-            plugin</description>
+            plugin. For performance reasons, this should only be enabled when necessary.</description>
           <defaultValue>false</defaultValue>
         </field>
         <field>
           <name>executions</name>
           <version>4.0.0</version>
-          <description>Multiple specifications of a set of goals, each having (possibly) different
-            configuration</description>
+          <description>Multiple specifications of a set of goals to execute during the build lifecycle, each having
+            (possibly) different
+            configuration.</description>
           <association>
             <type>PluginExecution</type>
             <multiplicity>*</multiplicity>
@@ -2455,7 +2295,8 @@
         </field>
         <field>
           <name>dependencies</name>
-          <description>Additional dependencies that this project needs to introduce to the plugin</description>
+          <description>Additional dependencies that this project needs to introduce to the plugin's
+            classloader.</description>
           <version>4.0.0</version>
           <association>
             <type>Dependency</type>
@@ -2466,7 +2307,7 @@
           <name>goals</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            NOT A VALID ELEMENT. LISTED TO ALLOW LEGACY REPOSITORY POMs TO PARSE.
+            <b>Deprecated</b>. Unused by Maven.
           ]]></description>
           <type>DOM</type>
         </field>
@@ -2530,15 +2371,20 @@
           <required>true</required>
           <type>String</type>
           <defaultValue>default</defaultValue>
+          <description>The identifier of this execution for labelling the goals during the build, and for matching
+            exections to merge during inheritance.</description>
         </field>
         <field>
           <name>phase</name>
           <version>4.0.0</version>
           <type>String</type>
+          <description>The build lifecycle phase to bind the goals in this execution to. If omitted, the goals will
+            be bound to the default specified in their metadata.</description>
         </field>
         <field>
           <name>goals</name>
           <version>4.0.0</version>
+          <description>The goals to execute with the given configuration.</description>
           <association>
             <type>String</type>
             <multiplicity>*</multiplicity>
@@ -2565,7 +2411,7 @@
           <name>dependencies</name>
           <version>4.0.0</version>
           <description>
-            The dependencies specified here are not validated until they
+            The dependencies specified here are not used until they
             are referenced in a POM within the group. This allows the
             specification of a "standard" version for a particular
             dependency.
@@ -2588,25 +2434,31 @@
     <class>
       <name>Reporting</name>
       <version>4.0.0</version>
-      <description>Section for management of reports and configuration</description>
+      <description>Section for management of reports and their configuration.</description>
       <fields>
         <field>
           <name>excludeDefaults</name>
           <version>4.0.0</version>
           <type>boolean</type>
-          <description>If true, then the default reports are not included in the site generation</description>
+          <description>If true, then the default reports are not included in the site generation. This includes the
+            reports in the "Project Info" menu.</description>
           <defaultValue>false</defaultValue>
         </field>
         <field>
           <name>outputDirectory</name>
           <version>4.0.0</version>
           <type>String</type>
-          <description>Where to store all of the generated reports</description>
+          <description><![CDATA[
+            Where to store all of the generated reports. The default is
+            <code>${project.build.directory}/site</code>
+            .
+          ]]></description>
+          <!-- TODO: why isn't default set here? -->
         </field>
         <field>
           <name>plugins</name>
           <version>4.0.0</version>
-          <description>The report plugins) to use and their configuration</description>
+          <description>The reporting plugins to use and their configuration.</description>
           <association>
             <type>ReportPlugin</type>
             <multiplicity>*</multiplicity>
@@ -2650,8 +2502,7 @@
       <superClass>ModelBase</superClass>
       <version>4.0.0</version>
       <description><![CDATA[
-        Modifications to the build process which is keyed on some
-        sort of environmental parameter.
+        Modifications to the build process which is activated based on environmental parameters or command line arguments.
       ]]></description>
       <fields>
         <field>
@@ -2659,8 +2510,8 @@
           <required>true</required>
           <version>4.0.0</version>
           <type>String</type>
-          <description>The ID of this build profile, for activation
-            purposes.</description>
+          <description>The identifier of this build profile. This used both for command line activation, and identifies
+            identical profiles to merge with during inheritance.</description>
         </field>
         <field>
           <name>activation</name>
@@ -2712,28 +2563,29 @@
       <version>4.0.0</version>
       <description><![CDATA[
         The conditions within the build runtime environment which will trigger
-        the automatic inclusion of the parent build profile.
+        the automatic inclusion of the build profile.
       ]]></description>
       <fields>
         <field>
           <name>activeByDefault</name>
           <version>4.0.0</version>
           <type>boolean</type>
-          <description>Flag specifying whether this profile is active as a default.</description>
+          <description>Flag specifying whether this profile is active by default.</description>
         </field>
         <field>
           <name>jdk</name>
           <version>4.0.0</version>
           <type>String</type>
           <description><![CDATA[
-            Specifies that this profile will be activated when a matching JDK is detected.
+            Specifies that this profile will be activated when a matching JDK is detected. For example, <code>1.4</code>
+            only activates on JDKs versioned 1.4, while <code>!1.4</code> matches any JDK that is not version 1.4.
           ]]></description>
         </field>
         <field>
           <name>os</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            Specifies that this profile will be activated when matching OS attributes are detected.
+            Specifies that this profile will be activated when matching operating system attributes are detected.
           ]]></description>
           <association>
             <type>ActivationOS</type>
@@ -2743,7 +2595,7 @@
           <name>property</name>
           <version>4.0.0</version>
           <description><![CDATA[
-            Specifies that this profile will be activated when this System property is specified.
+            Specifies that this profile will be activated when this system property is specified.
           ]]></description>
           <association>
             <type>ActivationProperty</type>
@@ -2775,13 +2627,13 @@
           <version>4.0.0</version>
           <type>String</type>
           <required>true</required>
-          <description>The name of the property to be used to activate a profile</description>
+          <description>The name of the property to be used to activate a profile.</description>
         </field>
         <field>
           <name>value</name>
           <version>4.0.0</version>
           <type>String</type>
-          <description>The value of the property to be used to activate a profile</description>
+          <description>The value of the property required to activate a profile.</description>
         </field>
       </fields>
     </class>
@@ -2797,25 +2649,27 @@
           <name>name</name>
           <version>4.0.0</version>
           <type>String</type>
-          <description>The name of the OS to be used to activate a profile</description>
+          <description><![CDATA[The name of the operating system to be used to activate the profile. This must be an exact match
+          of the <code>${os.name}</code> Java property, such as <code>Windows XP</code>.]]></description>
         </field>
         <field>
           <name>family</name>
           <version>4.0.0</version>
           <type>String</type>
-          <description>The general family of the OS to be used to activate a profile (e.g. 'windows')</description>
+          <description>
+            <![CDATA[The general family of the OS to be used to activate the profile, such as <code>windows</code> or <code>unix</code>.]]></description>
         </field>
         <field>
           <name>arch</name>
           <version>4.0.0</version>
           <type>String</type>
-          <description>The architecture of the OS to be used to activate a profile</description>
+          <description>The architecture of the operating system to be used to activate the profile.</description>
         </field>
         <field>
           <name>version</name>
           <version>4.0.0</version>
           <type>String</type>
-          <description>The version of the OS to be used to activate a profile</description>
+          <description>The version of the operating system to be used to activate the profile.</description>
         </field>
       </fields>
     </class>
@@ -2823,22 +2677,22 @@
       <name>ActivationFile</name>
       <version>4.0.0</version>
       <description><![CDATA[
-        This is the file specification used to activate a profile. The missing value will be a the location
-        of a file that needs to exist, and if it doesn't the profile must run.  On the other hand exists will test 
-        for the existence of the file and if it is there will run the profile.
+        This is the file specification used to activate the profile. The missing value will be the location

[... 160 lines stripped ...]


Mime
View raw message