Merge pull request #5 from jasper-schneider/docUpdates

Update Javadoc comments

Author: jasper-schneider

gulpfile.js

@@ -28,7 +28,7 @@ var isMac = (process.platform.lastIndexOf('darwin') === 0);
 
 var specRoot = args['spec-root'] || "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master";
 var projects = 'batchService'; // default
-var autoRestVersion = '0.17.0-Nightly20160706'; // default
+var autoRestVersion = '0.17.0-Nightly20160727'; // default
 if (args['autorest'] !== undefined) {
     autoRestVersion = args['autorest'];
 }

src/main/java/com/microsoft/azure/batch/AccountOperations.java

@@ -18,7 +18,7 @@
 import java.util.List;
 
 /**
- * Performs account related operations on an Azure Batch account.
+ * Performs account-related operations on an Azure Batch account.
  */
 public class AccountOperations implements IInheritedBehaviors {
 
@@ -34,20 +34,20 @@ public class AccountOperations implements IInheritedBehaviors {
     private BatchClient _parentBatchClient;
 
     /**
-     * Gets a list of behaviors that modify or customize requests to the Batch service.
+     * Gets a collection of behaviors that modify or customize requests to the Batch service.
      *
-     * @return A list of BatchClientBehavior
+     * @return A collection of {@link BatchClientBehavior} instances.
      */
     @Override
     public Collection<BatchClientBehavior> customBehaviors() {
         return _customBehaviors;
     }
 
     /**
-     * Sets a list of behaviors that modify or customize requests to the Batch service.
+     * Sets a collection of behaviors that modify or customize requests to the Batch service.
      *
-     * @param behaviors The collection of BatchClientBehavior classes
-     * @return The current instance
+     * @param behaviors The collection of {@link BatchClientBehavior} instances.
+     * @return The current instance.
      */
     @Override
     public IInheritedBehaviors withCustomBehaviors(Collection<BatchClientBehavior> behaviors) {
@@ -56,36 +56,36 @@ public IInheritedBehaviors withCustomBehaviors(Collection<BatchClientBehavior> b
     }
 
     /**
-     * Enumerates the node agent SKU values supported by Batch Service.
+     * Lists the node agent SKU values supported by the Batch service.
      *
-     * @return A collection of {@link NodeAgentSku} that can be used to enumerate node agent SKU values
-     * @throws BatchErrorException Exception thrown from REST call
-     * @throws IOException Exception thrown from serialization/deserialization
+     * @return A list of {@link NodeAgentSku} objects.
+     * @throws BatchErrorException Exception thrown when an error response is received from the Batch service.
+     * @throws IOException Exception thrown when there is an error in serialization/deserialization of data sent to/received from the Batch service.
      */
     public List<NodeAgentSku> listNodeAgentSkus() throws BatchErrorException, IOException {
         return listNodeAgentSkus(null, null);
     }
 
     /**
-     * Enumerates the node agent SKU values supported by Batch Service.
+     * Lists the node agent SKU values supported by the Batch service.
      *
      * @param detailLevel A {@link DetailLevel} used for filtering the list and for controlling which properties are retrieved from the service.
-     * @return An collection of {@link NodeAgentSku} that can be used to enumerate node agent SKU values
-     * @throws BatchErrorException Exception thrown from REST call
-     * @throws IOException Exception thrown from serialization/deserialization
+     * @return A list of {@link NodeAgentSku} objects.
+     * @throws BatchErrorException Exception thrown when an error response is received from the Batch service.
+     * @throws IOException Exception thrown when there is an error in serialization/deserialization of data sent to/received from the Batch service.
      */
     public List<NodeAgentSku> listNodeAgentSkus(DetailLevel detailLevel) throws BatchErrorException, IOException {
         return listNodeAgentSkus(detailLevel, null);
     }
 
     /**
-     * Enumerates the node agent SKU values supported by Batch Service.
+     * Lists the node agent SKU values supported by the Batch service.
      *
      * @param detailLevel A {@link DetailLevel} used for filtering the list and for controlling which properties are retrieved from the service.
      * @param additionalBehaviors A collection of {@link BatchClientBehavior} instances that are applied to the Batch service request.
-     * @return A collection of {@link NodeAgentSku} that can be used to enumerate node agent SKU values
-     * @throws BatchErrorException Exception thrown from REST call
-     * @throws IOException Exception thrown from serialization/deserialization
+     * @return A list of {@link NodeAgentSku} objects.
+     * @throws BatchErrorException Exception thrown when an error response is received from the Batch service.
+     * @throws IOException Exception thrown when there is an error in serialization/deserialization of data sent to/received from the Batch service.
      */
     public List<NodeAgentSku> listNodeAgentSkus(DetailLevel detailLevel, Iterable<BatchClientBehavior> additionalBehaviors) throws BatchErrorException, IOException {
         AccountListNodeAgentSkusOptions options = new AccountListNodeAgentSkusOptions();
@@ -97,4 +97,4 @@ public List<NodeAgentSku> listNodeAgentSkus(DetailLevel detailLevel, Iterable<Ba
 
         return response.getBody();
     }
-}
+}

src/main/java/com/microsoft/azure/batch/ApplicationOperations.java

@@ -20,9 +20,9 @@
 import java.util.List;
 
 /**
- * Performs application related operations on an Azure Batch account.
+ * Performs application-related operations on an Azure Batch account.
  */
-public class ApplicationOperations  implements IInheritedBehaviors {
+public class ApplicationOperations implements IInheritedBehaviors {
 
     ApplicationOperations(BatchClient batchClient, Collection<BatchClientBehavior> customBehaviors) {
         _parentBatchClient = batchClient;
@@ -36,20 +36,20 @@ public class ApplicationOperations  implements IInheritedBehaviors {
     private BatchClient _parentBatchClient;
 
     /**
-     * Gets a list of behaviors that modify or customize requests to the Batch service.
+     * Gets a collection of behaviors that modify or customize requests to the Batch service.
      *
-     * @return A list of BatchClientBehavior
+     * @return A collection of {@link BatchClientBehavior} instances.
      */
     @Override
     public Collection<BatchClientBehavior> customBehaviors() {
         return _customBehaviors;
     }
 
     /**
-     * Sets a list of behaviors that modify or customize requests to the Batch service.
+     * Sets a collection of behaviors that modify or customize requests to the Batch service.
      *
-     * @param behaviors The collection of BatchClientBehavior classes
-     * @return The current instance
+     * @param behaviors The collection of {@link BatchClientBehavior} instances.
+     * @return The current instance.
      */
     @Override
     public IInheritedBehaviors withCustomBehaviors(Collection<BatchClientBehavior> behaviors) {
@@ -58,23 +58,23 @@ public IInheritedBehaviors withCustomBehaviors(Collection<BatchClientBehavior> b
     }
 
     /**
-     * Enumerates the {@link ApplicationSummary applications} in the Batch account.
+     * Lists the {@link ApplicationSummary applications} in the Batch account.
      *
-     * @return A collection of {@link ApplicationSummary}
-     * @throws BatchErrorException Exception thrown from REST call
-     * @throws IOException Exception thrown from serialization/deserialization
+     * @return A list of {@link ApplicationSummary} objects.
+     * @throws BatchErrorException Exception thrown when an error response is received from the Batch service.
+     * @throws IOException Exception thrown when there is an error in serialization/deserialization of data sent to/received from the Batch service.
      */
     public List<ApplicationSummary> listApplications() throws BatchErrorException, IOException {
         return listApplications(null);
     }
 
     /**
-     * Enumerates the {@link ApplicationSummary applications}  in the Batch account.
+     * Lists the {@link ApplicationSummary applications} in the Batch account.
      *
      * @param additionalBehaviors A collection of {@link BatchClientBehavior} instances that are applied to the Batch service request.
-     * @return A collection of {@link ApplicationSummary}
-     * @throws BatchErrorException Exception thrown from REST call
-     * @throws IOException Exception thrown from serialization/deserialization
+     * @return A list of {@link ApplicationSummary} objects.
+     * @throws BatchErrorException Exception thrown when an error response is received from the Batch service.
+     * @throws IOException Exception thrown when there is an error in serialization/deserialization of data sent to/received from the Batch service.
      */
     public List<ApplicationSummary> listApplications(Iterable<BatchClientBehavior> additionalBehaviors) throws BatchErrorException, IOException {
         ApplicationListOptions options = new ApplicationListOptions();
@@ -91,8 +91,8 @@ public List<ApplicationSummary> listApplications(Iterable<BatchClientBehavior> a
      *
      * @param applicationId The ID of the application to get.
      * @return An {@link ApplicationSummary} containing information about the specified application.
-     * @throws BatchErrorException Exception thrown from REST call
-     * @throws IOException Exception thrown from serialization/deserialization
+     * @throws BatchErrorException Exception thrown when an error response is received from the Batch service.
+     * @throws IOException Exception thrown when there is an error in serialization/deserialization of data sent to/received from the Batch service.
      */
     public ApplicationSummary getApplication(String applicationId) throws BatchErrorException, IOException {
         return getApplication(applicationId, null);
@@ -104,8 +104,8 @@ public ApplicationSummary getApplication(String applicationId) throws BatchError
      * @param applicationId The ID of the application to get.
      * @param additionalBehaviors A collection of {@link BatchClientBehavior} instances that are applied to the Batch service request.
      * @return An {@link ApplicationSummary} containing information about the specified application.
-     * @throws BatchErrorException Exception thrown from REST call
-     * @throws IOException Exception thrown from serialization/deserialization
+     * @throws BatchErrorException Exception thrown when an error response is received from the Batch service.
+     * @throws IOException Exception thrown when there is an error in serialization/deserialization of data sent to/received from the Batch service.
      */
     public ApplicationSummary getApplication(String applicationId, Iterable<BatchClientBehavior> additionalBehaviors) throws BatchErrorException, IOException {
         ApplicationGetOptions options = new ApplicationGetOptions();

src/main/java/com/microsoft/azure/batch/BatchClient.java

@@ -32,9 +32,9 @@ public class BatchClient {
     private Collection<BatchClientBehavior> customBehaviors;
 
     /**
-     * Gets the internal proxy layer to be used for this client instance
+     * Gets the protocol layer service client that issues requests to the Azure Batch service.
      *
-     * @return The proxy layer client
+     * @return The protocol layer client.
      */
     public BatchServiceClient protocolLayer() {
         return this.protocolLayer;
@@ -58,108 +58,108 @@ private BatchClient(BatchSharedKeyCredentials credentials) {
     /**
      * Creates an instance of {@link BatchClient} associated with the specified credentials.
      *
-     * @param credentials The provided credential
-     * @return The new instance of BatchClient
+     * @param credentials A {@link BatchSharedKeyCredentials} object specifying the Batch account credentials.
+     * @return The new {@link BatchClient} instance.
      */
     public static BatchClient open(BatchSharedKeyCredentials credentials) {
         return new BatchClient(credentials);
     }
 
     /**
-     * Gets an {@link CertificateOperations} for performing certificate related operations on the associated account.
+     * Gets a {@link CertificateOperations} object for performing certificate-related operations on the associated account.
      *
-     * @return An instance of CertificateOperations class
+     * @return An instance of the {@link CertificateOperations} class.
      */
     public CertificateOperations certificateOperations() {
         return certificateOperations;
     }
 
     /**
-     * Gets an {@link JobOperations} for performing job related operations on the associated account.
+     * Gets a {@link JobOperations} object for performing job-related operations on the associated account.
      *
-     * @return An instance of JobOperations class
+     * @return An instance of the {@link JobOperations} class.
      */
     public JobOperations jobOperations() {
         return jobOperations;
     }
 
     /**
-     * Gets an {@link TaskOperations} for performing task related operations on the associated account.
+     * Gets a {@link TaskOperations} object for performing task-related operations on the associated account.
      *
-     * @return An instance of TaskOperations class
+     * @return An instance of the {@link TaskOperations} class.
      */
     public TaskOperations taskOperations() {
         return taskOperations;
     }
 
     /**
-     * Gets an {@link JobScheduleOperations} for performing job schedule related operations on the associated account.
+     * Gets a {@link JobScheduleOperations} object for performing job schedule-related operations on the associated account.
      *
-     * @return An instance of JobScheduleOperations class
+     * @return An instance of the {@link JobScheduleOperations} class.
      */
     public JobScheduleOperations jobScheduleOperations() {
         return jobScheduleOperations;
     }
 
     /**
-     * Gets an {@link FileOperations} for performing file-related operations on the associated account.
+     * Gets a {@link FileOperations} object for performing file-related operations on the associated account.
      *
-     * @return An instance of FileOperations class
+     * @return An instance of the {@link FileOperations} class.
      */
     public FileOperations fileOperations() {
         return fileOperations;
     }
 
     /**
-     * Gets an {@link PoolOperations} for performing pool related operations on the associated account.
+     * Gets a {@link PoolOperations} object for performing pool-related operations on the associated account.
      *
-     * @return An instance of PoolOperations class
+     * @return An instance of the {@link PoolOperations} class.
      */
     public PoolOperations poolOperations() {
         return poolOperations;
     }
 
     /**
-     * Gets an {@link ComputeNodeOperations} for performing compute node related operations on the associated account.
+     * Gets a {@link ComputeNodeOperations} object for performing compute node-related operations on the associated account.
      *
-     * @return An instance of ComputeNodeOperations class
+     * @return An instance of the {@link ComputeNodeOperations} class.
      */
     public ComputeNodeOperations computeNodeOperations() {
         return computeNodeOperations;
     }
 
     /**
-     * Gets an {@link ApplicationOperations} for performing application related operations on the associated account.
+     * Gets an {@link ApplicationOperations} object for performing application-related operations on the associated account.
      *
-     * @return An instance of ApplicationOperations class
+     * @return An instance of the {@link ApplicationOperations} class.
      */
     public ApplicationOperations applicationOperations() {
         return applicationOperations;
     }
 
     /**
-     * Gets an {@link AccountOperations} for performing account related operations on the associated account.
+     * Gets an {@link AccountOperations} object for performing account-related operations on the associated account.
      *
-     * @return An instance of AccountOperations class
+     * @return An instance of the {@link AccountOperations} class.
      */
     public AccountOperations accountOperations() {
         return accountOperations;
     }
 
     /**
-     * Gets a list of behaviors that modify or customize requests to the Batch service.
+     * Gets a collection of behaviors that modify or customize requests to the Batch service.
      *
-     * @return The collection of BatchClientBehavior classes.
+     * @return The collection of {@link BatchClientBehavior} instances.
      */
     public Collection<BatchClientBehavior> customBehaviors() {
         return customBehaviors;
     }
 
     /**
-     * Sets a list of behaviors that modify or customize requests to the Batch service.
+     * Sets a collection of behaviors that modify or customize requests to the Batch service.
      *
-     * @param customBehaviors The collection of BatchClientBehavior classes.
-     * @return A BatchClient instance
+     * @param customBehaviors The collection of {@link BatchClientBehavior} instances.
+     * @return The current instance.
      */
     public BatchClient withCustomBehaviors(Collection<BatchClientBehavior> customBehaviors) {
         this.customBehaviors = customBehaviors;

src/main/java/com/microsoft/azure/batch/BatchClientBehavior.java

@@ -7,7 +7,7 @@
 package com.microsoft.azure.batch;
 
 /**
- * Derived classes modify operational behaviors of a Azure Batch Service client.
+ * Classes derived from the BatchClientBehavior class modify operational behaviors of an Azure Batch client.
  */
 public abstract class BatchClientBehavior {
 }

src/main/java/com/microsoft/azure/batch/BatchErrorCodeStrings.java

@@ -7,7 +7,7 @@
 package com.microsoft.azure.batch;
 
 /**
- * Contains possible error code with BatchErrorException
+ * Error code strings returned from the Batch service.
  */
 public final class BatchErrorCodeStrings {
     // Batch Service
@@ -433,7 +433,7 @@ public final class BatchErrorCodeStrings {
     public static final String InvalidHeaderValue = "InvalidHeaderValue";
 
     /**
-     * The Batch service did not recognise the HTTP verb.
+     * The Batch service did not recognize the HTTP verb used for the request.
      */
     public static final String InvalidHttpVerb = "InvalidHttpVerb";