From 48428f7b4cb5b81885d372cc5297e77039ab9375 Mon Sep 17 00:00:00 2001
From: Stephane Bailliez <sbailliez@apache.org>
Date: Wed, 8 Aug 2001 19:34:20 +0000
Subject: [PATCH] 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                               |  7 ++++---
 docs/manual/using.html                                 |  4 ++++
 src/main/org/apache/tools/ant/Main.java                | 10 ++++++++++
 src/main/org/apache/tools/ant/Project.java             | 10 ++++++++++
 .../org/apache/tools/ant/types/defaults.properties     |  1 +
 5 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/docs/manual/running.html b/docs/manual/running.html
index 8cdc11761..1d6479e8e 100644
--- a/docs/manual/running.html
+++ b/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] ...]]
diff --git a/docs/manual/using.html b/docs/manual/using.html
index a67c693b5..7c635ae74 100644
--- a/docs/manual/using.html
+++ b/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
diff --git a/src/main/org/apache/tools/ant/Main.java b/src/main/org/apache/tools/ant/Main.java
index 8b295d9bd..e12581b76 100644
--- a/src/main/org/apache/tools/ant/Main.java
+++ b/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
      */
diff --git a/src/main/org/apache/tools/ant/Project.java b/src/main/org/apache/tools/ant/Project.java
index e6f759326..745a501ae 100644
--- a/src/main/org/apache/tools/ant/Project.java
+++ b/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) {
diff --git a/src/main/org/apache/tools/ant/types/defaults.properties b/src/main/org/apache/tools/ant/types/defaults.properties
index 020d21c17..d268128ae 100644
--- a/src/main/org/apache/tools/ant/types/defaults.properties
+++ b/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