doc updates in the tasks, for autogenerated docs

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

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/CSharp.java

@@ -75,81 +75,57 @@ import java.io.File;
 /**
  *  Compiles C# source into executables or modules.
  *
- *  The task will only work on win2K until other platforms support
- *  csc.exe or an equivalent. CSC.exe must be on the execute path too. <p>
- *
- *  All parameters are optional: &lt;csc/&gt; should suffice to produce a debug
- *  build of all *.cs files. References to external files do require explicit
- *  enumeration, so are one of the first attributes to consider adding. <p>
- *
+ * csc.exe must be on the execute path, unless another executable
+ * or the full path to that executable is specified in the <tt>executable</tt>
+ * parameter
+ * <p>
+ * All parameters are optional: &lt;csc/&gt; should suffice to produce a debug
+ * build of all *.cs files. However, naming an <tt>destFile</tt>stops the
+ * csc compiler from choosing an output name from random, and
+ * allows the dependency checker to determine if the file is out of date.
+ * <p>
  *  The task is a directory based task, so attributes like <b>includes="*.cs"
  *  </b> and <b>excludes="broken.cs"</b> can be used to control the files pulled
  *  in. By default, all *.cs files from the project folder down are included in
  *  the command. When this happens the output file -if not specified- is taken
  *  as the first file in the list, which may be somewhat hard to control.
- *  Specifying the output file with <b>'outfile'</b> seems prudent. <p>
- *
- *  <p>
- *
- *  TODO
- *  <ol>
- *    <li> is incremental build still broken in beta-1?
- *    <li> is Win32Icon broken?
- *    <li> all the missing options
- *  </ol>
- *  <p>
- *
- *  History
- *  <Table>
- *
- *    <tr>
- *
- *      <td>
- *        0.3
- *      </td>
- *
- *      <td>
- *        Beta 1 edition
- *      </td>
- *
- *      <td>
- *        To avoid having to remember which assemblies to include, the task
- *        automatically refers to the main dotnet libraries in Beta1.
- *      </tr>
- *
- *      <tr>
- *
- *        <td>
- *          0.2
- *        </td>
- *
- *        <td>
- *          Slightly different
- *        </td>
- *
- *        <td>
- *          Split command execution to a separate class;
- *        </tr>
- *
- *        <tr>
+ *  Specifying the output file with <tt>destFile</tt> seems prudent. <p>
  *
- *          <td>
- *            0.1
- *          </td>
+ * <p>
+ * For more complex source trees, nested <tt>src</tt> elemements can be
+ * supplied. When such an element is present, the implicit fileset is ignored.
+ * This makes sense, when you think about it :)
+ * <p>
  *
- *          <td>
- *            "I can't believe it's so rudimentary"
- *          </td>
+ * References to external files can be made through the references attribute,
+ * or (since Ant1.6), via nested &lt;reference&gt; filesets. With the latter,
+ * the timestamps of the references are also used in the dependency
+ * checking algorithm.
+ * <p>
  *
- *          <td>
- *            First pass; minimal builds only support;
- *          </tr>
+ * Example
  *
- *        </table>
+ * <pre>&lt;csc
+ * 	optimize=&quot;true&quot;
+ * 	debug=&quot;false&quot;
+ * 	docFile=&quot;documentation.xml&quot;
+ * 	warnLevel=&quot;4&quot;
+ * 	unsafe=&quot;false&quot;
+ * 	targetType=&quot;exe&quot;
+ * 	incremental=&quot;false&quot;
+ * 	mainClass = &quot;MainApp&quot;
+ * 	destFile=&quot;NetApp.exe&quot;
+ * 	&gt;
+ * 	     &lt;src dir="src" includes="*.cs" /&gt;
+ *       &lt;reference file="${testCSC.dll}" /&gt;
+ *       &lt;define name="RELEASE" /&gt;
+ *       &lt;define name="DEBUG" if="debug.property"/&gt;
+ *       &lt;define name="def3" unless="def3.property"/&gt;
+ *    &lt;/csc&gt;
+ * </pre>
  *
  *
- * @author      Steve Loughran steve_l@iseran.com
- * @version     0.5
+ * @author      Steve Loughran
  * @ant.task    name="csc" category="dotnet"
  * @since Ant 1.3
  */

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/Ilasm.java

@@ -69,9 +69,11 @@ import org.apache.tools.ant.types.EnumeratedAttribute;
 import org.apache.tools.ant.types.FileSet;
 
 /**
- *  Assembles .NET Intermediate Language files. The task will only work
- *  on win2K until other platforms support csc.exe or an equivalent. ilasm.exe
- *  must be on the execute path too. <p>
+ * Assembles .NET Intermediate Language files.
+ * ilasm.exe must be on the execute path, unless another executable
+ * or the full path to that executable is specified in the <tt>executable</tt>
+ * parameter
+ *  <p>
  *
  *  <p>
  *
@@ -86,9 +88,9 @@ import org.apache.tools.ant.types.FileSet;
  *  The task is a directory based task, so attributes like <b>includes="*.il"
  *  </b> and <b>excludes="broken.il"</b> can be used to control the files pulled
  *  in. You can also use nested &lt;src&gt filesets to refer to source.
- *
- * @author     Steve Loughran steve_l@iseran.com
- * @version    0.6
+ * <p>
+ * 
+ * @author     Steve Loughran
  * @ant.task    name="ilasm" category="dotnet"
  */
 

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/Ildasm.java

@@ -56,6 +56,7 @@ package org.apache.tools.ant.taskdefs.optional.dotnet;
 import org.apache.tools.ant.types.EnumeratedAttribute;
 import org.apache.tools.ant.BuildException;
 import org.apache.tools.ant.Task;
+import org.apache.tools.ant.Project;
 import org.apache.tools.ant.util.FileUtils;
 
 import java.io.File;
@@ -352,16 +353,26 @@ public class Ildasm extends Task {
     }
 
     /**
-     *
-     * @return
+     * Test for disassembly being needed; use existence and granularity
+     * correct date stamps
+     * @return true iff a rebuild is required.
      */
     private boolean isDisassemblyNeeded() {
         if (!destFile.exists()) {
+            log("Destination file does not exist: a build is required",
+                    Project.MSG_VERBOSE);
             return true;
         }
         long sourceTime = sourceFile.lastModified();
         long destTime = destFile.lastModified();
-        return sourceTime > (destTime + FileUtils.newFileUtils().getFileTimestampGranularity());
+        if(sourceTime > (destTime + FileUtils.newFileUtils().getFileTimestampGranularity())) {
+            log("Source file is newer than the dest file: a rebuild is required",
+                    Project.MSG_VERBOSE);
+            return true;
+        } else {
+            log("The .il file is up to date", Project.MSG_VERBOSE);
+            return false;
+        }
 
     }
     /**
@@ -370,6 +381,9 @@ public class Ildasm extends Task {
      */
     public void execute() throws BuildException {
         validate();
+        if(!isDisassemblyNeeded()) {
+            return;
+        }
         NetCommand command = new NetCommand(this, "ildasm", executable);
         command.setFailOnError(true);
         //fill in args
@@ -423,6 +437,7 @@ public class Ildasm extends Task {
         } catch (BuildException e) {
             //forcibly delete the output file in case of trouble
             if (destFile.exists()) {
+                log("Deleting destination file as it may be corrupt");
                 destFile.delete();
             }
             //then rethrow the exception

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/ImportTypelib.java

@@ -57,16 +57,28 @@ package org.apache.tools.ant.taskdefs.optional.dotnet;
 import org.apache.tools.ant.Task;
 import org.apache.tools.ant.BuildException;
 import org.apache.tools.ant.Project;
+import org.apache.tools.ant.util.FileUtils;
 
 import java.io.File;
 
 /**
- * Wrapper to .NET's tlbimport; imports a tlb file to a NET assembly
+ * Import a COM type library into the .NET framework.
+ * <p>
+ *
+ * This task is a wrapper to .NET's tlbimport; it imports a tlb file to a NET assembly
  * by generating a binary assembly (.dll) that contains all the binding
- * metadata. Uses date timestamps to minimise rebuilds.
+ * metadata. It uses date timestamps to minimise rebuilds.
+ * <p>
+ * Example
+ * <pre>
+ *     &lt;importtypelib
+ *       srcfile="xerces.tlb"
+ *       destfile="xerces.dll"
+ *       namespace="Apache.Xerces"/&gt;
+ * </pre>
  * @since Ant 1.6
  * @author steve loughran
- * @ant.task    name="ImportTypelib" category="dotnet"
+ * @ant.task category="dotnet"
  */
 public class ImportTypelib extends Task {
 
@@ -162,7 +174,7 @@ public class ImportTypelib extends Task {
             throw new BuildException(
                     "destination file is a directory");
         }
-        if (srcFile != null || !srcFile.exists()) {
+        if (srcFile == null || !srcFile.exists()) {
             throw new BuildException(
                     "source file does not exist");
         }
@@ -175,6 +187,31 @@ public class ImportTypelib extends Task {
         }
     }
 
+    /**
+     * Test for disassembly being needed; use existence and granularity
+     * correct date stamps
+     * @return true iff a rebuild is required.
+     */
+    private boolean isExecuteNeeded() {
+        if (!destFile.exists()) {
+            log("Destination file does not exist: a build is required",
+                    Project.MSG_VERBOSE);
+            return true;
+        }
+        long sourceTime = srcFile.lastModified();
+        long destTime = destFile.lastModified();
+        if (sourceTime > (destTime + FileUtils.newFileUtils().getFileTimestampGranularity())) {
+            log("Source file is newer than the dest file: a rebuild is required",
+                    Project.MSG_VERBOSE);
+            return true;
+        } else {
+            log("The output file is up to date", Project.MSG_VERBOSE);
+            return false;
+        }
+
+    }
+
+
     /**
      * Create a typelib command
      * @exception BuildException if something goes wrong with the build
@@ -185,9 +222,7 @@ public class ImportTypelib extends Task {
             + " to assembly " + destFile
             + " in namespace " + namespace, Project.MSG_VERBOSE);
         //rebuild unless the dest file is newer than the source file
-        if (srcFile.exists() && destFile.exists()
-            && srcFile.lastModified() <= destFile.lastModified()) {
-            log("The typelib is up to date", Project.MSG_VERBOSE);
+        if(!isExecuteNeeded()) {
             return;
         }
 
@@ -205,5 +240,6 @@ public class ImportTypelib extends Task {
             command.addArgument("/unsafe");
         }
         command.addArgument(extraOptions);
+        command.runCommand();
     }
 }

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/JSharp.java

@@ -60,14 +60,16 @@ import org.apache.tools.ant.BuildException;
  * Compile J# source down to a managed .NET application.
  * <p>
  * J# is not Java. But it is the language closest to Java in the .NET framework.
- * This task compiles jsharp source (assumes a .jsl extension, incidentally), and
+ * This task compiles jsharp source (.java files), and
  * generates a .NET managed exe or dll.
  * <p>
- * See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vjsharp/html/vjoriMicrosoftVisualJ.asp
- * for vjc command options in glory detail.
+ *
+ * @see <A=ref="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vjsharp/html/vjoriMicrosoftVisualJ.asp">
+ * Visual J++ online documentation</a>
+ *
  * @author Steve Loughran
  * @since ant1.6
- * @ant.task    name="jsharpc" category="dotnet"
+ * @ant.task category="dotnet"
  */
 public class JSharp extends DotnetCompile {
 
@@ -122,14 +124,12 @@ public class JSharp extends DotnetCompile {
         return ";";
     }
 
-
-
     /**
      * Get the extension of filenames to compile.
      * @return The string extension of files to compile.
      */
     public String getFileExtension() {
-        return ".jsl";
+        return ".java";
     }
 
     /**

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/VisualBasicCompile.java

@@ -59,13 +59,52 @@ import org.apache.tools.ant.BuildException;
 
 /**
  * This task compiles Visual Basic.NET source into executables or modules.
- * The task will only work on win2K until other platforms support vbc.exe or
- * an equivalent. VBC.exe must be on the execute path, too.
+ * The task requires vbc.exe on the execute path, unless it or an equivalent
+ * program is specified in the <tt>executable</tt> parameter
  *
  * <p>
  * All parameters are optional: &lt;vbc/&gt; should suffice to produce a debug
  * build of all *.vb files.
  *
+ * <p>
+
+ * The task is a directory based task, so attributes like
+ * <tt>includes=&quot;**\/*.vb&quot;</tt> and
+ * <tt>excludes=&quot;broken.vb&quot;</tt> can be used to control
+ * the files pulled in. By default,
+ * all *.vb files from the project folder down are included in the command.
+ * When this happens the destFile -if not specified-
+ * is taken as the first file in the list, which may be somewhat hard to control.
+   Specifying the output file with <tt>destfile</tt> is prudent.
+ </p>
+ <p>
+ * Also, dependency checking only works if destfile is set.
+ *
+ * As with &lt;csc&gt; nested <tt>src</tt> filesets of source,
+ * reference filesets, definitions and resources can be provided.
+ *
+ * <p>
+ * Example
+ * </p>
+ * <pre>&lt;vbc
+ *   optimize=&quot;true&quot;
+ *   debug=&quot;false&quot;
+ *   warnLevel=&quot;4&quot;
+ *   targetType=&quot;exe&quot;
+ *   definitions=&quot;RELEASE&quot;
+ *   excludes=&quot;src/unicode_class.vb&quot;
+ *   mainClass = &quot;MainApp&quot;
+ *   destFile=&quot;NetApp.exe&quot;
+ *   optionExplicit=&quot;true&quot;
+ *   optionCompare=&quot;text&quot;
+ *   references="System.Xml,System.Web.Xml"
+ *   &gt;
+ *          &lt;reference file="${testCSC.dll}" /&gt;
+ *          &lt;define name="RELEASE" /&gt;
+ *          &lt;define name="DEBUG" if="debug.property"/&gt;
+ *          &lt;define name="def3" unless="def2.property"/&gt;
+ *   &lt;/vbc&gt;
+ </pre>
  * @author Brian Felder bfelder@providence.org
  * @author Steve Loughran
  * @ant.task    name="vbc" category="dotnet"

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/WsdlToDotnet.java

@@ -60,11 +60,23 @@ import org.apache.tools.ant.Task;
 /**
  * Converts a WSDL file or URL resource into a .NET language.
  *
+ * Why add a wrapper to the MS WSDL tool?
+ * So that you can verify that your web services, be they written with Axis or
+ *anyone else's SOAP toolkit, work with .NET clients.
+ *
+ *This task is dependency aware when using a file as a source and destination;
+ *so if you &lt;get&gt; the file (with <code>usetimestamp="true"</code>) then
+ *you only rebuild stuff when the WSDL file is changed. Of course,
+ *if the server generates a new timestamp every time you ask for the WSDL,
+ *this is not enough...use the &lt;filesmatch&gt; &lt;condition&gt; to
+ *to byte for byte comparison against a cached WSDL file then make
+ *the target conditional on that test failing.
+
  * See "Creating an XML Web Service Proxy", "wsdl.exe" docs in
  * the framework SDK documentation
  * @author      Steve Loughran 
  * @version     0.5
- * @ant.task    name="wsdltodotnet" category="dotnet"
+ * @ant.task    category="dotnet"
  * @since       Ant 1.5
  */