Convenient description task that allows a multiple line description of a buildfile

with a <description> elment.
Submitted by Craeg K. Strong <cstrong@arielpartners.com>


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@269523 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/running.html

@@ -46,9 +46,10 @@ When omitted, the target that is specified in the
 <code>default</code> attribute of the <code>&lt;project&gt;</code> tag is
 used.</p>
 
-<p>The <nobr><code>-projecthelp</code></nobr>
-option gives a list of this project's
-targets. First those with a description, then those without one.</p>
+<p>The <nobr><code>-projecthelp</code></nobr> option prints out the
+description of the project, if it exists, followed by a list of this
+project's targets. First those with a description, then those without
+one.</p>
 
 <p>Command-line option summary:</p>
 <pre>ant [options] [target [target2 [target3] ...]]

docs/manual/using.html

@@ -42,6 +42,10 @@ to be unique. (For additional information, see the
     <td align="center" valign="top">No</td>
   </tr>
 </table>
+<p>Optionally, a description for the project can be provided as a
+top-level &lt;description&gt; element (see the <a
+href="CoreTypes/description.html">description</a> type).</p>
+
 <p>Each project defines one or more <i>targets</i>.
 A target is a set of <i>tasks</i> you want
 to be executed. When starting Ant, you can select which target(s) you

src/main/org/apache/tools/ant/Main.java

@@ -458,6 +458,7 @@ public class Main {
                 System.setErr(err);
             }
             if (projectHelp) {
+                printDescription(project);
                 printTargets(project);
             }
         }
@@ -581,6 +582,15 @@ public class Main {
         return antVersion;
     }
 
+     /**
+      * Print the project description, if any
+      */
+    private static void printDescription(Project project) {
+       if (project.getDescription() != null) {
+          System.out.println(project.getDescription());
+       }
+    }
+
     /**
      * Print out a list of all targets in the current buildfile
      */

src/main/org/apache/tools/ant/Project.java

@@ -98,6 +98,7 @@ public class Project {
     public static final String TOKEN_END = FilterSet.DEFAULT_TOKEN_END;
 
     private String name;
+    private String description;
 
     private Hashtable properties = new Hashtable();
     private Hashtable userProperties = new Hashtable();
@@ -318,6 +319,15 @@ public class Project {
         return name;
     }
 
+    public void setDescription(String description) {
+        this.description = description;
+    }
+
+   // Will return null if no description has been set
+    public String getDescription() {
+        return description;
+    }
+
     /** @deprecated */
     public void addFilter(String token, String value) {
         if (token == null) {

src/main/org/apache/tools/ant/types/defaults.properties

@@ -4,4 +4,5 @@ filelist=org.apache.tools.ant.types.FileList
 patternset=org.apache.tools.ant.types.PatternSet
 mapper=org.apache.tools.ant.types.Mapper
 filterset=org.apache.tools.ant.types.FilterSet
+description=org.apache.tools.ant.types.Description