Changed -projecthelp to show targets that have a description before

the other targets.
Submitted by:	Marcel Schutte <marcel@schutte.com>


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

WHATSNEW

@@ -35,7 +35,7 @@ behavior has been dropped.
 Other changes:
 --------------
 
-* New tasks: antstructure, cab, execon, fail, ftp, genkey, junit, sql, javacc, jjtree, starteam.
+* New tasks: antstructure, cab, execon, fail, ftp, genkey, jlink, junit, sql, javacc, jjtree, starteam.
 
 * New tasks mparse pending documentation.
 

build.xml

@@ -131,7 +131,7 @@
   <!-- =================================================================== -->
   <!-- Creates the binary structure                                        -->
   <!-- =================================================================== -->
-  <target name="main" depends="jar">
+  <target name="main" depends="jar" description="Creates the binary structure">
      <mkdir dir="${bin.dir}"/>
      <copydir src="${src.bin.dir}" dest="${bin.dir}"/>
      <chmod perm="+x">
@@ -146,7 +146,7 @@
   <!-- =================================================================== -->
   <!-- Creates the API documentation                                       -->
   <!-- =================================================================== -->
-  <target name="javadocs" depends="prepare">
+  <target name="javadocs" depends="prepare" description="Creates the API documentation">
     <mkdir dir="${build.javadocs}"/>
     <javadoc packagenames="${packages}"
              sourcepath="${basedir}/${src.dir}"
@@ -162,7 +162,7 @@
   <!-- =================================================================== -->
   <!-- Creates the distribution                                            -->
   <!-- =================================================================== -->
-  <target name="dist" depends="main,jar,javadocs">
+  <target name="dist" depends="main,jar,javadocs" description="Creates the distribution">
      <mkdir dir="${ant.dist.dir}"/>
      <mkdir dir="${ant.dist.dir}/bin"/>
      <mkdir dir="${ant.dist.dir}/lib"/>
@@ -207,7 +207,7 @@
   <!-- =================================================================== -->
   <!-- Installs the ant.jar library and binary files into ant.home         -->
   <!-- =================================================================== -->
-  <target name="bootstrap" depends="main">
+  <target name="bootstrap" depends="main" description="Installs the ant.jar library and binary files into ant.home">
     <echo message="copying bootstrapped files into bin and lib"/>
     <copydir src="${lib.dir}" dest="lib"/>
     <copydir src="${bin.dir}" dest="bin"/>

docs/index.html

@@ -174,21 +174,23 @@ buildfile (see the <a href="#property">property task</a>).
 This can be done with the <i>-D&lt;property&gt;=&lt;value&gt;</i>
 option, where <i>&lt;property&gt;</i> is the name of the property and <i>&lt;value&gt;</i>
 the value.</p>
-<p>To more options are <i>-quiet</i> which instructs Ant to print less
+<p>Two more options are <i>-quiet</i> which instructs Ant to print less
 information on the console when running. The option <i>-verbose</i> on the other
 hand makes Ant print more information on the console.</p>
-<p>It is also possible to specify the target that should be executed. Default
-the target that is mentioned in the <i>default</i> attribute of the project is
-used. This can be overridden by adding the target name to the end of the
-commandline.</p>
+<p>It is also possible to specify one or more targets that should be executed. When omitted the target that is mentioned in the <i>default</i> attribute of the project is
+used.</p>
+<p>The <i>-projecthelp</i> option gives a list of this projects targets. First those with a description and then those without one.</p>
 <p>Commandline option summary:</p>
-<pre>ant [options] [target]
+<pre>ant [options] [target [target2 [target3] ...]]
 Options:
 -help                  print this message
+-projecthelp           print project help information
 -version               print the version information and exit
 -quiet                 be extra quiet
 -verbose               be extra verbose
+-emacs                 produce logging information without adornments
 -logfile &lt;file&gt;        use given file for log
+-logger &lt;classname&gt;    the class which is to perform logging
 -listener &lt;classname&gt;  add an instance of class as a project listener
 -buildfile &lt;file&gt;      use given buildfile
 -D&lt;property&gt;=&lt;value&gt;   use value for given property</pre>
@@ -302,6 +304,7 @@ href="#tstamp">tstamp</a> tasks in a so called initialization target, on which
 all other targets depend. Make sure that target is always the first one in
 the depends list of the other targets. In this manual, most initialization targets
 have the name "init".</p>
+<p>The optional <i>description</i> attribute can be used to provide a one line description of this target that is printed by the <i>-projecthelp</i> commandline option.</p>
 <p>A target has the following attributes:</p>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
@@ -332,6 +335,11 @@ have the name "init".</p>
       for this target to execute.</td>
     <td align="center" valign="top">No</td>
   </tr>
+  <tr>
+    <td valign="top">description</td>
+    <td valign="top">a short description of this targets function.</td>
+    <td align="center" valign="top">No</td>
+  </tr>
 </table>
 <h3>Tasks</h3>
 <p>A task is a piece of code that can be executed.</p>

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

@@ -95,7 +95,7 @@ public class Main {
 
     /**
      * The Ant logger class. There may be only one logger. It will have the
-     * right to use the 'out' PrintStream. The class must implements the BuildLogger 
+     * right to use the 'out' PrintStream. The class must implements the BuildLogger
      * interface
      */
     private String loggerClassname = null;
@@ -114,7 +114,7 @@ public class Main {
      * Indicates we should only parse and display the project help information
      */
     private boolean projectHelp = false;
-    
+
     /**
      * Command line entry point. This method kicks off the building
      * of a project object and executes a build using either a given
@@ -276,7 +276,7 @@ public class Main {
         try {
             addBuildListeners(project);
             project.fireBuildStarted();
-            
+
             project.init();
 
             // set user-define properties
@@ -355,12 +355,12 @@ public class Main {
                 logger = (BuildLogger)(Class.forName(loggerClassname).newInstance());
             }
             catch (ClassCastException e) {
-                System.err.println("The specified logger class " + loggerClassname + 
+                System.err.println("The specified logger class " + loggerClassname +
                                          " does not implement the BuildLogger interface");
                 throw new RuntimeException();
             }
             catch (Exception e) {
-                System.err.println("Unable to instantiate specified logger class " + 
+                System.err.println("Unable to instantiate specified logger class " +
                                            loggerClassname + " : " + e.getClass().getName());
                 throw new RuntimeException();
             }
@@ -368,12 +368,12 @@ public class Main {
         else {
             logger = new DefaultLogger();
         }
-        
+
         logger.setMessageOutputLevel(msgOutputLevel);
         logger.setOutputPrintStream(out);
         logger.setErrorPrintStream(err);
         logger.setEmacsMode(emacsMode);
-        
+
         return logger;
     }
 
@@ -383,7 +383,7 @@ public class Main {
     private static void printUsage() {
         String lSep = System.getProperty("line.separator");
         StringBuffer msg = new StringBuffer();
-        msg.append("ant [options] [target]" + lSep);
+        msg.append("ant [options] [target [target2 [target3] ...]]" + lSep);
         msg.append("Options: " + lSep);
         msg.append("  -help                  print this message" + lSep);
         msg.append("  -projecthelp           print project help information" + lSep);
@@ -422,49 +422,78 @@ public class Main {
             System.err.println("Could not load the version information.");
         }
     }
-    
+
     /**
      * Print out a list of all targets in the current buildfile
      */
     private static void printTargets(Project project) {
-        // find the target with the longest name and
-        // filter out the targets with no description
+        // find the target with the longest name
         int maxLength = 0;
         Enumeration ptargets = project.getTargets().elements();
         String targetName;
         String targetDescription;
         Target currentTarget;
-        Vector names = new Vector();
-        Vector descriptions = new Vector();
+        // split the targets in top-level and sub-targets depending
+        // on the presence of a description
+        Vector topNames = new Vector();
+        Vector topDescriptions = new Vector();
+        Vector subNames = new Vector();
 
         while (ptargets.hasMoreElements()) {
             currentTarget = (Target)ptargets.nextElement();
             targetName = currentTarget.getName();
             targetDescription = currentTarget.getDescription();
+            // maintain a sorted list of targets
             if (targetDescription == null) {
-                targetDescription = "";
-            }
-            
-            names.addElement(targetName);
-            descriptions.addElement(targetDescription);
+                int pos = findTargetPosition(subNames, targetName);
+                subNames.insertElementAt(targetName, pos);
+            } else {
+                int pos = findTargetPosition(topNames, targetName);
+                topNames.insertElementAt(targetName, pos);
+                topDescriptions.insertElementAt(targetDescription, pos);
             if (targetName.length() > maxLength) {
                 maxLength = targetName.length();
             }
         }
+        }
+        printTargets(topNames, topDescriptions, "Main targets:", maxLength);
+        printTargets(subNames, null, "Subtargets:", 0);
+    }
 
+    /**
+     * Search for the insert position to keep names a sorted list of Strings
+     */
+    private static int findTargetPosition(Vector names, String name) {
+        int res = names.size();
+        for (int i=0; i<names.size() && res == names.size(); i++) {
+            if (name.compareTo((String)names.elementAt(i)) < 0) {
+                res = i;
+            }
+        }
+        return res;
+    }
+
+    /**
+     * Output a formatted list of target names with an optional description
+     */
+    private static void printTargets(Vector names, Vector descriptions, String heading, int maxlen) {
         // now, start printing the targets and their descriptions
         String lSep = System.getProperty("line.separator");
         // got a bit annoyed that I couldn't find a pad function
         String spaces = "    ";
-        while (spaces.length()<maxLength) {
+        while (spaces.length()<maxlen) {
             spaces += spaces;
         }
         StringBuffer msg = new StringBuffer();
-        msg.append("Targets: " + lSep);
+        msg.append(heading + lSep + lSep);
         for (int i=0; i<names.size(); i++) {
-            msg.append(" -"+names.elementAt(i));
-            msg.append(spaces.substring(0, maxLength - ((String)names.elementAt(i)).length() + 2));
-            msg.append(descriptions.elementAt(i)+lSep);
+            msg.append(" ");
+            msg.append(names.elementAt(i));
+            if (descriptions != null) {
+                msg.append(spaces.substring(0, maxlen - ((String)names.elementAt(i)).length() + 2));
+                msg.append(descriptions.elementAt(i));
+            }
+            msg.append(lSep);
         }
         System.out.println(msg.toString());
     }