[AutoPR batch/data-plane] Update documentation of Batch data plane swagger.

lib/services/batch/LICENSE.txt

@@ -1,21 +1,21 @@
-The MIT License (MIT)
-
-Copyright (c) 2018 Microsoft
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+The MIT License (MIT)
+
+Copyright (c) 2018 Microsoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lib/services/batch/lib/models/autoPoolSpecification.js

@@ -41,7 +41,7 @@ class AutoPoolSpecification {
    * @member {string} [pool.vmSize] For information about available sizes of
    * virtual machines for Cloud Services pools (pools created with
    * cloudServiceConfiguration), see Sizes for Cloud Services
-   * (http://azure.microsoft.com/documentation/articles/cloud-services-sizes-specs/).
+   * (https://azure.microsoft.com/documentation/articles/cloud-services-sizes-specs/).
    * Batch supports all Cloud Services VM sizes except ExtraSmall, A1V2 and
    * A2V2. For information about available VM sizes for pools using images from
    * the Virtual Machines Marketplace (pools created with
@@ -229,7 +229,10 @@ class AutoPoolSpecification {
    * such as environment variable expansion. If you want to take advantage of
    * such features, you should invoke the shell in the command line, for
    * example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in
-   * Linux.
+   * Linux. If the command line refers to file paths, it should use a relative
+   * path (relative to the task working directory), or use the Batch provided
+   * environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object} [pool.startTask.containerSettings] When this is
    * specified, all directories recursively below the AZ_BATCH_NODE_ROOT_DIR
    * (the root of Azure Batch directories on the node) are mapped into the

lib/services/batch/lib/models/cloudJob.js

@@ -76,7 +76,10 @@ class CloudJob {
    * such as environment variable expansion. If you want to take advantage of
    * such features, you should invoke the shell in the command line, for
    * example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in
-   * Linux.
+   * Linux. If the command line refers to file paths, it should use a relative
+   * path (relative to the task working directory), or use the Batch provided
+   * environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object} [jobManagerTask.containerSettings] If the pool that will
    * run this task has containerConfiguration set, this must be set as well. If
    * the pool that will run this task doesn't have containerConfiguration set,
@@ -113,12 +116,15 @@ class CloudJob {
    * default is infinite, i.e. the task directory will be retained until the
    * compute node is removed or reimaged.
    * @member {number} [jobManagerTask.constraints.maxTaskRetryCount] Note that
-   * this value specifically controls the number of retries. The Batch service
-   * will try the task once, and may then retry up to this limit. For example,
-   * if the maximum retry count is 3, Batch tries the task up to 4 times (one
-   * initial try and 3 retries). If the maximum retry count is 0, the Batch
-   * service does not retry the task. If the maximum retry count is -1, the
-   * Batch service retries the task without limit.
+   * this value specifically controls the number of retries for the task
+   * executable due to a nonzero exit code. The Batch service will try the task
+   * once, and may then retry up to this limit. For example, if the maximum
+   * retry count is 3, Batch tries the task up to 4 times (one initial try and
+   * 3 retries). If the maximum retry count is 0, the Batch service does not
+   * retry the task after the first attempt. If the maximum retry count is -1,
+   * the Batch service retries the task without limit. Resource files and
+   * application packages are only downloaded again if the task is retried on a
+   * new compute node.
    * @member {boolean} [jobManagerTask.killJobOnCompletion] If true, when the
    * Job Manager task completes, the Batch service marks the job as complete.
    * If any tasks are still running at this time (other than Job Release),
@@ -171,7 +177,7 @@ class CloudJob {
    * 'job', which grants access to all operations related to the job which
    * contains the task.
    * @member {boolean} [jobManagerTask.allowLowPriorityNode] The default value
-   * is false.
+   * is true.
    * @member {object} [jobPreparationTask] The Job Preparation task. The Job
    * Preparation task is a special task run on each node before any other task
    * of the job.
@@ -188,7 +194,10 @@ class CloudJob {
    * features such as environment variable expansion. If you want to take
    * advantage of such features, you should invoke the shell in the command
    * line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c
-   * MyCommand" in Linux.
+   * MyCommand" in Linux. If the command line refers to file paths, it should
+   * use a relative path (relative to the task working directory), or use the
+   * Batch provided environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object} [jobPreparationTask.containerSettings] When this is
    * specified, all directories recursively below the AZ_BATCH_NODE_ROOT_DIR
    * (the root of Azure Batch directories on the node) are mapped into the
@@ -220,12 +229,15 @@ class CloudJob {
    * The default is infinite, i.e. the task directory will be retained until
    * the compute node is removed or reimaged.
    * @member {number} [jobPreparationTask.constraints.maxTaskRetryCount] Note
-   * that this value specifically controls the number of retries. The Batch
-   * service will try the task once, and may then retry up to this limit. For
-   * example, if the maximum retry count is 3, Batch tries the task up to 4
-   * times (one initial try and 3 retries). If the maximum retry count is 0,
-   * the Batch service does not retry the task. If the maximum retry count is
-   * -1, the Batch service retries the task without limit.
+   * that this value specifically controls the number of retries for the task
+   * executable due to a nonzero exit code. The Batch service will try the task
+   * once, and may then retry up to this limit. For example, if the maximum
+   * retry count is 3, Batch tries the task up to 4 times (one initial try and
+   * 3 retries). If the maximum retry count is 0, the Batch service does not
+   * retry the task after the first attempt. If the maximum retry count is -1,
+   * the Batch service retries the task without limit. Resource files and
+   * application packages are only downloaded again if the task is retried on a
+   * new compute node.
    * @member {boolean} [jobPreparationTask.waitForSuccess] If true and the Job
    * Preparation task fails on a compute node, the Batch service retries the
    * Job Preparation task up to its maximum retry count (as specified in the
@@ -273,7 +285,10 @@ class CloudJob {
    * such as environment variable expansion. If you want to take advantage of
    * such features, you should invoke the shell in the command line, for
    * example using "cmd /c MyCommand" in Windows or "/bin/sh -c MyCommand" in
-   * Linux.
+   * Linux. If the command line refers to file paths, it should use a relative
+   * path (relative to the task working directory), or use the Batch provided
+   * environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object} [jobReleaseTask.containerSettings] When this is
    * specified, all directories recursively below the AZ_BATCH_NODE_ROOT_DIR
    * (the root of Azure Batch directories on the node) are mapped into the
@@ -354,7 +369,7 @@ class CloudJob {
    * information about available sizes of virtual machines for Cloud Services
    * pools (pools created with cloudServiceConfiguration), see Sizes for Cloud
    * Services
-   * (http://azure.microsoft.com/documentation/articles/cloud-services-sizes-specs/).
+   * (https://azure.microsoft.com/documentation/articles/cloud-services-sizes-specs/).
    * Batch supports all Cloud Services VM sizes except ExtraSmall, A1V2 and
    * A2V2. For information about available VM sizes for pools using images from
    * the Virtual Machines Marketplace (pools created with
@@ -570,7 +585,10 @@ class CloudJob {
    * shell features such as environment variable expansion. If you want to take
    * advantage of such features, you should invoke the shell in the command
    * line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c
-   * MyCommand" in Linux.
+   * MyCommand" in Linux. If the command line refers to file paths, it should
+   * use a relative path (relative to the task working directory), or use the
+   * Batch provided environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object}
    * [poolInfo.autoPoolSpecification.pool.startTask.containerSettings] When
    * this is specified, all directories recursively below the
@@ -706,7 +724,9 @@ class CloudJob {
    * of terminatejob. Any other string is a user-defined reason specified in a
    * call to the 'Terminate a job' operation.
    * @member {object} [stats] Resource usage statistics for the entire lifetime
-   * of the job.
+   * of the job. The statistics may not be immediately available. The Batch
+   * service performs periodic roll-up of statistics. The typical delay is
+   * about 30 minutes.
    * @member {string} [stats.url]
    * @member {date} [stats.startTime]
    * @member {date} [stats.lastUpdateTime]

lib/services/batch/lib/models/cloudJobSchedule.js

@@ -130,7 +130,10 @@ class CloudJobSchedule {
    * shell features such as environment variable expansion. If you want to take
    * advantage of such features, you should invoke the shell in the command
    * line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c
-   * MyCommand" in Linux.
+   * MyCommand" in Linux. If the command line refers to file paths, it should
+   * use a relative path (relative to the task working directory), or use the
+   * Batch provided environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object} [jobSpecification.jobManagerTask.containerSettings] If
    * the pool that will run this task has containerConfiguration set, this must
    * be set as well. If the pool that will run this task doesn't have
@@ -174,12 +177,15 @@ class CloudJobSchedule {
    * is removed or reimaged.
    * @member {number}
    * [jobSpecification.jobManagerTask.constraints.maxTaskRetryCount] Note that
-   * this value specifically controls the number of retries. The Batch service
-   * will try the task once, and may then retry up to this limit. For example,
-   * if the maximum retry count is 3, Batch tries the task up to 4 times (one
-   * initial try and 3 retries). If the maximum retry count is 0, the Batch
-   * service does not retry the task. If the maximum retry count is -1, the
-   * Batch service retries the task without limit.
+   * this value specifically controls the number of retries for the task
+   * executable due to a nonzero exit code. The Batch service will try the task
+   * once, and may then retry up to this limit. For example, if the maximum
+   * retry count is 3, Batch tries the task up to 4 times (one initial try and
+   * 3 retries). If the maximum retry count is 0, the Batch service does not
+   * retry the task after the first attempt. If the maximum retry count is -1,
+   * the Batch service retries the task without limit. Resource files and
+   * application packages are only downloaded again if the task is retried on a
+   * new compute node.
    * @member {boolean} [jobSpecification.jobManagerTask.killJobOnCompletion] If
    * true, when the Job Manager task completes, the Batch service marks the job
    * as complete. If any tasks are still running at this time (other than Job
@@ -237,7 +243,7 @@ class CloudJobSchedule {
    * 'job', which grants access to all operations related to the job which
    * contains the task.
    * @member {boolean} [jobSpecification.jobManagerTask.allowLowPriorityNode]
-   * The default value is false.
+   * The default value is true.
    * @member {object} [jobSpecification.jobPreparationTask] If a job has a Job
    * Preparation task, the Batch service will run the Job Preparation task on a
    * compute node before starting any tasks of that job on that compute node.
@@ -255,7 +261,10 @@ class CloudJobSchedule {
    * advantage of shell features such as environment variable expansion. If you
    * want to take advantage of such features, you should invoke the shell in
    * the command line, for example using "cmd /c MyCommand" in Windows or
-   * "/bin/sh -c MyCommand" in Linux.
+   * "/bin/sh -c MyCommand" in Linux. If the command line refers to file paths,
+   * it should use a relative path (relative to the task working directory), or
+   * use the Batch provided environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object} [jobSpecification.jobPreparationTask.containerSettings]
    * When this is specified, all directories recursively below the
    * AZ_BATCH_NODE_ROOT_DIR (the root of Azure Batch directories on the node)
@@ -294,12 +303,15 @@ class CloudJobSchedule {
    * compute node is removed or reimaged.
    * @member {number}
    * [jobSpecification.jobPreparationTask.constraints.maxTaskRetryCount] Note
-   * that this value specifically controls the number of retries. The Batch
-   * service will try the task once, and may then retry up to this limit. For
-   * example, if the maximum retry count is 3, Batch tries the task up to 4
-   * times (one initial try and 3 retries). If the maximum retry count is 0,
-   * the Batch service does not retry the task. If the maximum retry count is
-   * -1, the Batch service retries the task without limit.
+   * that this value specifically controls the number of retries for the task
+   * executable due to a nonzero exit code. The Batch service will try the task
+   * once, and may then retry up to this limit. For example, if the maximum
+   * retry count is 3, Batch tries the task up to 4 times (one initial try and
+   * 3 retries). If the maximum retry count is 0, the Batch service does not
+   * retry the task after the first attempt. If the maximum retry count is -1,
+   * the Batch service retries the task without limit. Resource files and
+   * application packages are only downloaded again if the task is retried on a
+   * new compute node.
    * @member {boolean} [jobSpecification.jobPreparationTask.waitForSuccess] If
    * true and the Job Preparation task fails on a compute node, the Batch
    * service retries the Job Preparation task up to its maximum retry count (as
@@ -359,7 +371,10 @@ class CloudJobSchedule {
    * shell features such as environment variable expansion. If you want to take
    * advantage of such features, you should invoke the shell in the command
    * line, for example using "cmd /c MyCommand" in Windows or "/bin/sh -c
-   * MyCommand" in Linux.
+   * MyCommand" in Linux. If the command line refers to file paths, it should
+   * use a relative path (relative to the task working directory), or use the
+   * Batch provided environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object} [jobSpecification.jobReleaseTask.containerSettings] When
    * this is specified, all directories recursively below the
    * AZ_BATCH_NODE_ROOT_DIR (the root of Azure Batch directories on the node)
@@ -452,7 +467,7 @@ class CloudJobSchedule {
    * information about available sizes of virtual machines for Cloud Services
    * pools (pools created with cloudServiceConfiguration), see Sizes for Cloud
    * Services
-   * (http://azure.microsoft.com/documentation/articles/cloud-services-sizes-specs/).
+   * (https://azure.microsoft.com/documentation/articles/cloud-services-sizes-specs/).
    * Batch supports all Cloud Services VM sizes except ExtraSmall, A1V2 and
    * A2V2. For information about available VM sizes for pools using images from
    * the Virtual Machines Marketplace (pools created with
@@ -672,7 +687,10 @@ class CloudJobSchedule {
    * advantage of shell features such as environment variable expansion. If you
    * want to take advantage of such features, you should invoke the shell in
    * the command line, for example using "cmd /c MyCommand" in Windows or
-   * "/bin/sh -c MyCommand" in Linux.
+   * "/bin/sh -c MyCommand" in Linux. If the command line refers to file paths,
+   * it should use a relative path (relative to the task working directory), or
+   * use the Batch provided environment variable
+   * (https://docs.microsoft.com/en-us/azure/batch/batch-compute-node-environment-variables).
    * @member {object}
    * [jobSpecification.poolInfo.autoPoolSpecification.pool.startTask.containerSettings]
    * When this is specified, all directories recursively below the
@@ -785,7 +803,9 @@ class CloudJobSchedule {
    * schedule as metadata. The Batch service does not assign any meaning to
    * metadata; it is solely for the use of user code.
    * @member {object} [stats] The lifetime resource usage statistics for the
-   * job schedule.
+   * job schedule. The statistics may not be immediately available. The Batch
+   * service performs periodic roll-up of statistics. The typical delay is
+   * about 30 minutes.
    * @member {string} [stats.url]
    * @member {date} [stats.startTime]
    * @member {date} [stats.lastUpdateTime]