Fix the javadoc comments and add @ant.attribute tags for xdocs documentation generation

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

src/main/org/apache/tools/ant/taskdefs/optional/sos/SOS.java

@@ -94,8 +94,9 @@ public abstract class SOS extends Task implements SOSCmd {
     protected Commandline commandLine;
 
     /**
-     * Flag to disable the cache when set;
-     * optional needed if SOSHOME is set as an environment variable., default false
+     * Flag to disable the cache when set.
+     * Required if SOSHOME is set as an environment variable.
+     * Defaults to false.
      *
      * @param  nocache  True to disable caching.
      */
@@ -104,7 +105,7 @@ public abstract class SOS extends Task implements SOSCmd {
     }
 
     /**
-     * Flag that disables compression when set; optional, default false
+     * Flag to disable compression when set. Defaults to false.
      *
      * @param  nocompress  True to disable compression.
      */
@@ -113,8 +114,8 @@ public abstract class SOS extends Task implements SOSCmd {
     }
 
     /**
-     * Set the directory where soscmd(.exe) is located;
-     * optional, soscmd must be on the path if omitted.
+     * The directory where soscmd(.exe) is located.
+     * soscmd must be on the path if omitted.
      *
      * @param  dir  The new sosCmd value
      */
@@ -123,16 +124,18 @@ public abstract class SOS extends Task implements SOSCmd {
     }
 
     /**
-     * Set the SourceSafe username; required.
+     * The SourceSafe username.
      *
      * @param  username  The new username value
+     *
+     * @ant.attribute group="required"
      */
     public final void setUsername(String username) {
         sosUsername = username;
     }
 
     /**
-     * Set the SourceSafe password; optional.
+     * The SourceSafe password.
      *
      * @param  password  The new password value
      */
@@ -141,9 +144,11 @@ public abstract class SOS extends Task implements SOSCmd {
     }
 
     /**
-     * Set the SourceSafe project path; required.
+     * The SourceSafe project path.
      *
      * @param  projectpath  The new projectpath value
+     *
+     * @ant.attribute group="required"
      */
     public final void setProjectPath(String projectpath) {
         if (projectpath.startsWith(SOSCmd.PROJECT_PREFIX)) {
@@ -154,17 +159,18 @@ public abstract class SOS extends Task implements SOSCmd {
     }
 
     /**
-     * Set the path to the location of the ss.ini file;
-     * required.
+     * The path to the location of the ss.ini file.
      *
      * @param  vssServerPath  The new vssServerPath value
+     *
+     * @ant.attribute group="required"
      */
     public final void setVssServerPath(String vssServerPath) {
         this.vssServerPath = vssServerPath;
     }
 
     /**
-     * The path to the SourceOffSite home directory
+     * Path to the SourceOffSite home directory.
      *
      * @param  sosHome  The new sosHome value
      */
@@ -173,17 +179,19 @@ public abstract class SOS extends Task implements SOSCmd {
     }
 
     /**
-     * Sets the address and port of SourceOffSite Server,
-     * for example 192.168.0.1:8888.; required.
+     * The address and port of SourceOffSite Server,
+     * for example 192.168.0.1:8888.
      *
      * @param  sosServerPath  The new sosServerPath value
+     *
+     * @ant.attribute group="required"
      */
     public final void setSosServerPath(String sosServerPath) {
         this.sosServerPath = sosServerPath;
     }
 
     /**
-     * Override the working directory and get to the specified path; optional.
+     * Override the working directory and get to the specified path.
      *
      * @param  path  The new localPath value
      */
@@ -192,7 +200,7 @@ public abstract class SOS extends Task implements SOSCmd {
     }
 
     /**
-     * Enable verbose output; optional, default false
+     * Enable verbose output. Defaults to false.
      *
      * @param  verbose  True for verbose output.
      */

src/main/org/apache/tools/ant/taskdefs/optional/sos/SOSCheckin.java

@@ -58,95 +58,16 @@ import org.apache.tools.ant.types.Commandline;
 /**
  * Commits and unlocks files in Visual SourceSafe via a SourceOffSite server.
  *
- * <p>
- * The following attributes are interpretted:
- * <table border="1">
- *   <tr>
- *     <th>Attribute</th>
- *     <th>Values</th>
- *     <th>Required</th>
- *   </tr>
- *   <tr>
- *     <td>soscmddir</td>
- *     <td>Directory which contains soscmd(.exe) <br>
- *     soscmd(.exe) must be in the path if this is not specified</td>
- *     <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>vssserverpath</td>
- *      <td>path to the srcsafe.ini  - eg. \\server\vss\srcsafe.ini</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>sosserverpath</td>
- *      <td>address and port of the SOS server  - eg. 192.168.0.1:8888</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>projectpath</td>
- *      <td>SourceSafe project path</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>file</td>
- *      <td>Filename to act upon<br> If no file is specified then act upon the project</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>username</td>
- *      <td>SourceSafe username</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>password</td>
- *      <td>SourceSafe password</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>localpath</td>
- *      <td>Override the working directory and get to the specified path</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>soshome</td>
- *      <td>The path to the SourceOffSite home directory</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>nocompression</td>
- *      <td>true or false - disable compression</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>recursive</td>
- *      <td>true or false - Only works with the CheckOutProject command</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>nocache</td>
- *      <td>true or false - Only needed if SOSHOME is set as an enviroment variable</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>verbose</td>
- *      <td>true or false - Status messages are displayed</td>
- *      <td>No</td>
- *   </tr>
- *   <td>comment</td>
- *      <td>A comment to be applied to all files being checked in</td>
- *      <td>No</td>
- *   </tr>
- * </table>
- *
  * @author    Jesse Stockall
+ *
+ * @ant.task name="soscheckin" category="scm"
  */
-
 public class SOSCheckin extends SOS {
 
     /**
-     * Set the Filename to act upon; optional.
-     * If no file is specified then the tasks
-     * act upon the project
+     * The filename to act upon.
+     * If no file is specified then the task
+     * acts upon the project.
      *
      * @param  filename  The new file value
      */
@@ -155,7 +76,7 @@ public class SOSCheckin extends SOS {
     }
 
     /**
-     * Flag to recursively apply the action; optional, default false
+     * Flag to recursively apply the action. Defaults to false.
      *
      * @param  recursive  True for recursive operation.
      */
@@ -164,8 +85,7 @@ public class SOSCheckin extends SOS {
     }
 
     /**
-     * Set the comment to apply to all files being labelled;
-     * optional
+     * The comment to apply to all files being labelled.
      *
      * @param  comment  The new comment value
      */

src/main/org/apache/tools/ant/taskdefs/optional/sos/SOSCheckout.java

@@ -58,91 +58,16 @@ import org.apache.tools.ant.types.Commandline;
 /**
  * Retrieves and locks files in Visual SourceSafe via a SourceOffSite server.
  *
- * <p>
- * The following attributes are interpretted:
- * <table border="1">
- *   <tr>
- *     <th>Attribute</th>
- *     <th>Values</th>
- *     <th>Required</th>
- *   </tr>
- *   <tr>
- *     <td>soscmddir</td>
- *     <td>Directory which contains soscmd(.exe) <br>
- *     soscmd(.exe) must be in the path if this is not specified</td>
- *     <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>vssserverpath</td>
- *      <td>path to the srcsafe.ini  - eg. \\server\vss\srcsafe.ini</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>sosserverpath</td>
- *      <td>address and port of the SOS server  - eg. 192.168.0.1:8888</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>projectpath</td>
- *      <td>SourceSafe project path</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>file</td>
- *      <td>Filename to act upon<br> If no file is specified then act upon the project</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>username</td>
- *      <td>SourceSafe username</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>password</td>
- *      <td>SourceSafe password</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>localpath</td>
- *      <td>Override the working directory and get to the specified path</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>soshome</td>
- *      <td>The path to the SourceOffSite home directory</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>nocompression</td>
- *      <td>true or false - disable compression</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>recursive</td>
- *      <td>true or false - Only works with the CheckOutProject command</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>nocache</td>
- *      <td>true or false - Only needed if SOSHOME is set as an enviroment variable</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>verbose</td>
- *      <td>true or false - Status messages are displayed</td>
- *      <td>No</td>
- *   </tr>
- * </table>
- *
  * @author    Jesse Stockall
+ *
+ * @ant.task name="soscheckout" category="scm"
  */
-
 public class SOSCheckout extends SOS {
 
     /**
-     * Set the Filename to act upon; optional.
-     * If no file is specified then the tasks
-     * act upon the project
+     * The filename to act upon.
+     * If no file is specified then the task
+     * acts upon the project.
      *
      * @param  filename  The new file value
      */
@@ -151,7 +76,7 @@ public class SOSCheckout extends SOS {
     }
 
     /**
-     * Flag to recursively apply the action; optional, default false
+     * Flag to recursively apply the action. Defaults to false.
      *
      * @param  recursive  True for recursive operation.
      */

src/main/org/apache/tools/ant/taskdefs/optional/sos/SOSGet.java

@@ -58,102 +58,17 @@ import org.apache.tools.ant.types.Commandline;
 /**
  * Retrieves a read-only copy of the specified project or file
  * from Visual SourceSafe via a SourceOffSite server.
- * <p>
- * The following attributes are interpretted:
- * <table border="1">
- *    <tbody>
- *      <tr>
- *         <th>Attribute</th>
- *         <th>Values</th>
- *         <th>Required</th>
- *       </tr>
- *       <tr>
- *         <td>soscmddir</td>
- *         <td>Directory which contains soscmd(.exe) <br>
- *         soscmd(.exe) must be in the path if this is not specified</td>
- *         <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>vssserverpath</td>
- *          <td>path to the srcsafe.ini  - eg. \\server\vss\srcsafe.ini</td>
- *          <td>Yes</td>
- *       </tr>
- *       <tr>
- *          <td>sosserverpath</td>
- *          <td>address and port of the SOS server  - eg. 192.168.0.1:8888</td>
- *          <td>Yes</td>
- *       </tr>
- *       <tr>
- *          <td>projectpath</td>
- *          <td>SourceSafe project path</td>
- *          <td>Yes</td>
- *       </tr>
- *       <tr>
- *          <td>file</td>
- *          <td>Filename to act upon<br>
- *              If no file is specified then act upon the project</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>username</td>
- *          <td>SourceSafe username</td>
- *          <td>Yes</td>
- *       </tr>
- *       <tr>
- *          <td>password</td>
- *          <td>SourceSafe password</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>localpath</td>
- *          <td>Override the working directory and get to the specified path</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>soshome</td>
- *          <td>The path to the SourceOffSite home directory</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>nocompression</td>
- *          <td>true or false - disable compression</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>recursive</td>
- *          <td>true or false - Only works with the GetProject command</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>version</td>
- *          <td>a version number to get - Only works with the GetFile command</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>label</td>
- *          <td>a label version to get - Only works with the GetProject command</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>nocache</td>
- *          <td>true or false - Only needed if SOSHOME is set as an enviroment variable</td>
- *          <td>No</td>
- *       </tr>
- *       <tr>
- *          <td>verbose</td>
- *         <td>true or false - Status messages are displayed</td>
- *        <td>No</td>
- *      </tr>
  *
  * @author    Jesse Stockall
+ *
+ * @ant.task name="sosget" category="scm"
  */
-
 public class SOSGet extends SOS {
 
     /**
-     * Set the Filename to act upon; optional.
+     * The Filename to act upon.
      * If no file is specified then the tasks
-     * act upon the project
+     * act upon the project.
      *
      * @param  filename  The new file value
      */
@@ -162,7 +77,7 @@ public class SOSGet extends SOS {
     }
 
     /**
-     * Flag to recursively apply the action; optional, default false
+     * Flag to recursively apply the action. Defaults to false
      *
      * @param  recursive  True for recursive operation.
      */
@@ -172,7 +87,7 @@ public class SOSGet extends SOS {
 
     /**
      * Set the version number to get -
-     * only works with SOSGet on a file; optional.
+     * only works with SOSGet on a file.
      *
      * @param  version  The new version value
      */
@@ -181,7 +96,7 @@ public class SOSGet extends SOS {
     }
 
     /**
-     * Set the labeled version to operate on in SourceSafe
+     * The labeled version to operate on in SourceSafe.
      *
      * @param  label  The new label value
      */

src/main/org/apache/tools/ant/taskdefs/optional/sos/SOSLabel.java

@@ -58,69 +58,15 @@ import org.apache.tools.ant.types.Commandline;
 
 /**
  * Labels Visual SourceSafe files via a SourceOffSite server.
- * <p>
- * The following attributes are interpreted:
- * <table border="1">
- *   <tr>
- *     <th>Attribute</th>
- *     <th>Values</th>
- *     <th>Required</th>
- *   </tr>
- *   <tr>
- *     <td>soscmddir</td>
- *     <td>Directory which contains soscmd(.exe) <br>
- *     soscmd(.exe) must be in the path if this is not specified</td>
- *     <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>vssserverpath</td>
- *      <td>path to the srcsafe.ini  - eg. \\server\vss\srcsafe.ini</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>sosserverpath</td>
- *      <td>address and port of the SOS server  - eg. 192.168.0.1:8888</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>projectpath</td>
- *      <td>SourceSafe project</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>username</td>
- *      <td>SourceSafe username</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>password</td>
- *      <td>SourceSafe password</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>label</td>
- *      <td>The label to apply to a project</td>
- *      <td>Yes</td>
- *   </tr>
- *   <tr>
- *      <td>comment</td>
- *      <td>A comment to be applied to all files being labeled</td>
- *      <td>No</td>
- *   </tr>
- *   <tr>
- *      <td>verbose</td>
- *      <td>true or false - Status messages are displayed</td>
- *      <td>No</td>
- *   </tr>
- * </table>
  *
  * @author    Jesse Stockall
+ *
+ * @ant.task name="soslabel" category="scm"
  */
-
 public class SOSLabel extends SOS {
 
     /**
-     * Set the version number to label; optional.
+     * The version number to label.
      *
      * @param  version  The new version value
      */
@@ -129,17 +75,18 @@ public class SOSLabel extends SOS {
     }
 
     /**
-     * Set the label to apply the the files in SourceSafe.
+     * The label to apply the the files in SourceSafe.
      *
      * @param  label  The new label value
+     *
+     * @ant.attribute group="required"
      */
     public void setLabel(String label) {
         super.setInternalLabel(label);
     }
 
     /**
-     * Set the comment to apply to all files being labelled;
-     * optional
+     * The comment to apply to all files being labelled.
      *
      * @param  comment  The new comment value
      */