Update doc to match editor reviewed doc (#69)

mathworks · Mar 20, 2024 · d6ec7c2 · d6ec7c2
1 parent 838d77d
commit d6ec7c2
Show file tree

Hide file tree

Showing 8 changed files with 101 additions and 86 deletions.
diff --git a/src/@orb.yml b/src/@orb.yml
@@ -1,7 +1,7 @@
 version: 2.1
 
 description: >
-  Run MATLAB and Simulink as part of your build pipeline.
+  Run MATLAB as part of your build pipeline.
 
 display:
   source_url: https://github.com/mathworks/matlab-circleci-orb

diff --git a/src/commands/install.yml b/src/commands/install.yml
@@ -1,21 +1,23 @@
 description: >
-  Install a specific version of MATLAB. (If you use this command to install transformation products,
-  such as MATLAB Coder and MATLAB Compiler, the command does not automatically license such products for you.)
+  Install a specific release of MATLAB. If you do not specify a release, the command installs the latest
+  release of MATLAB. As part of the installation process, the command prepends MATLAB to the `PATH` system
+  environment variable.
 
 parameters:
   products:
     description: >
       Products to install in addition to MATLAB, specified as a list of product names separated by
       spaces. You can specify this parameter to install most MathWorks products and support packages. The
-      command uses MATLAB Package Manager (`mpm`) to install products. For a list of supported
-      products and their correctly formatted names, see
+      command uses MATLAB Package Manager (`mpm`) to install products. If you use this parameter to install
+      transformation products, such as MATLAB Coder and MATLAB Compiler, the command does not automatically
+      license such products for you. For a list of supported products and their correctly formatted names, see
       https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md#product-installation-options.
     type: string
     default: ''
   release:
     description: >
-      MATLAB release to install. You can specify R2021a or a later release. By default, the value of `release`
-      is `latest`. If you do not specify `release`, the command installs the latest release of MATLAB.
+      MATLAB release to install. You can specify R2021a or a later release. If you do not specify `release`,
+      the command installs the latest release of MATLAB.
     type: string
     default: 'latest'
   no-output-timeout:

diff --git a/src/commands/run-build.yml b/src/commands/run-build.yml
@@ -1,13 +1,16 @@
 description: >
-  Run builds using the MATLAB build tool. Use this command to run the tasks in the plan returned
-  by a file named buildfile.m in the root of your repository. To use the run-build command, you
-  need MATLAB R2022b or a later release.
+  Run a build using the MATLAB build tool. Use this command to run the tasks specified in a file
+  named `buildfile.m` in the root of your repository. To use the `run-build` command, you need MATLAB
+  R2022b or a later release.
 
 parameters:
   tasks:
     description: >
-      Space-separated list of tasks to run. If not specified, the command runs the default tasks
-      in the plan returned by buildfile.m as well as all the tasks on which they depend.
+      Tasks to run, specified as a list of task names separated by spaces. If a task accepts arguments,
+      enclose them in parentheses. If you do not specify `tasks`, the command runs the default tasks in
+      `buildfile.m` as well as all the tasks on which they depend. MATLAB exits with exit code 0 if the
+      tasks run without error. Otherwise, MATLAB terminates with a nonzero exit code, which causes the
+      command to fail.
     type: string
     default: ""
   build-options:
@@ -20,8 +23,9 @@ parameters:
     default: ""
   startup-options:
     description: >
-      MATLAB startup options. If you specify more than one option, use a space to
-      separate the options.
+      MATLAB startup options, specified as a list of options separated by spaces. For more
+      information about startup options, see
+      https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
     type: string
     default: ""
   no-output-timeout:

diff --git a/src/commands/run-command.yml b/src/commands/run-command.yml
@@ -1,21 +1,22 @@
 description: >
-  Execute a MATLAB script, function, or statement. MATLAB exits with exit code 0 if the specified
-  script, function, or statement executes successfully without error. Otherwise, MATLAB terminates
-  with a nonzero exit code, which causes the build to fail. You can use the assert or error
-  functions in the command to ensure that builds fail when necessary. When you use this command,
-  all of the required files must be on the MATLAB search path.
+  Run MATLAB scripts, functions, and statements. When you use this command, all of the required
+  files must be on the MATLAB search path.
 
 parameters:
   command:
     description: >
-      Script, function, or statement to execute. If the value of command is the name of a MATLAB
-      script or function, do not specify the file extension. If you specify more than one MATLAB
-      command, use a comma or semicolon to separate the commands.
+      Script, function, or statement to execute. If the value of `command` is the name of a MATLAB
+      script or function, do not specify the file extension. If you specify more than one script,
+      function, or statement, use a comma or semicolon to separate them. MATLAB exits with exit
+      code 0 if the specified script, function, or statement executes successfully without error.
+      Otherwise, MATLAB terminates with a nonzero exit code, which causes the command to fail.
+      To fail the command in certain conditions, use the `assert` or `error` function.
     type: string
   startup-options:
     description: >
-      MATLAB startup options. If you specify more than one option, use a space to
-      separate the options.
+      MATLAB startup options, specified as a list of options separated by spaces. For more
+      information about startup options, see
+      https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
     type: string
     default: ""
   no-output-timeout:

diff --git a/src/commands/run-tests.yml b/src/commands/run-tests.yml
@@ -1,105 +1,113 @@
 description: >
-  Run all tests in a MATLAB project and generate test artifacts. MATLAB includes any files in your
-  project that have a Test label. If your pipeline does not leverage a MATLAB project, then MATLAB
-  includes all tests in the the root of your repository including its subfolders.
+  Run MATLAB and Simulink tests and generate artifacts. By default, the command includes any files
+  in your project that have a `Test` label. If your pipeline does not use a MATLAB project, or if
+  it uses a MATLAB release before R2019a, then the command includes all tests in the root of your
+  repository and in any of its subfolders. The command fails if any of the included tests fails.
 
 parameters:
-  test-results-junit:
+  source-folder:
     description: >
-      Path to write test results report in JUnit XML format.
+      Location of the folder containing source code, relative to the project root folder. The
+      specified folder and its subfolders are added to the top of the MATLAB search path. If
+      you specify `source-folder` and then generate a coverage report, MATLAB uses only the source
+      code in the specified folder and its subfolders to generate the report. You can specify multiple
+      folders using a colon-separated or semicolon-separated list.
     type: string
     default: ''
-  code-coverage-cobertura:
+  select-by-folder:
     description: >
-      Path to write code coverage report in Cobertura XML format.
+      Location of the folder used to select test suite elements, relative to the project root folder.
+      To create a test suite, MATLAB uses only the tests in the specified folder and its subfolders.
+      You can specify multiple folders using a colon-separated or semicolon-separated list.
     type: string
     default: ''
-  code-coverage-html:
+  select-by-tag:
     description: >
-      Path to write code coverage report in HTML format.
+      Test tag used to select test suite elements. To create a test suite, MATLAB uses only the test elements
+      with the specified tag.
     type: string
     default: ''
-  source-folder:
+  strict:
     description: >
-      Location of the folder containing source code, relative to the project root folder. The
-      specified folder and its subfolders are added to the top of the MATLAB search path. To
-      generate a code coverage report, MATLAB uses only the source code in the specified folder and
-      its subfolders. You can specify multiple folders using a colon-separated or a
-      semicolon-separated list.
-    type: string
-    default: ''
-  select-by-folder:
+      Option to apply strict checks when running tests, specified as `false` or `true`. If you specify
+      a value of `true`, the command generates a qualification failure whenever a test issues a warning.
+    type: boolean
+    default: false
+  use-parallel:
     description: >
-      Location of the folder used to select test suite elements, relative to the project root folder.
-      To generate a test suite, MATLAB uses only the tests in the specified folder and its subfolders.
-      You can specify multiple folders using a colon-separated or a semicolon-separated list.
+      Option to run tests in parallel, specified as `false` or `true`. If the test runner configuration
+      is suited for parallelization, you can specify a value of `true` to run tests in parallel. This
+      parameter requires a Parallel Computing Toolbox license.
+    type: boolean
+    default: false
+  output-detail:
+    description: >
+      Amount of event detail displayed for the test run, specified as `none`, `terse`, `concise`, `detailed`,
+      or `verbose`. By default, the command displays failing and logged events at the `detailed` level and test
+      run progress at the `concise` level.
     type: string
     default: ''
-  select-by-tag:
+  logging-level:
     description: >
-      Test tag used to select test suite elements. To generate a test suite, MATLAB uses only the test elements
-      with the specified tag.
+      Maximum verbosity level for logged diagnostics included for the test run, specified as `none`, `terse`,
+      `concise`, `detailed`, or `verbose`. By default, the command includes diagnostics logged at the `terse` level.
     type: string
     default: ''
-  model-coverage-cobertura:
+  test-results-pdf:
     description: >
-      Path to write model coverage report in Cobertura XML format.
+      Path to write the test results in PDF format. On macOS platforms, this parameter is supported in MATLAB R2020b and later.
     type: string
     default: ''
-  model-coverage-html:
+  test-results-junit:
     description: >
-      Path to write model coverage report in HTML format.
+      Path to write the test results in JUnit-style XML format.
     type: string
     default: ''
   test-results-simulink-test:
     description: >
-      Path to export Simulink Test Manager results in MLDATX format.
+      Path to export Simulink Test Manager results in MLDATX format. This parameter requires a Simulink Test license, and
+      is supported in MATLAB R2019a and later.
     type: string
     default: ''
   test-results-html:
     description: >
-      Path to write test results report in HTML format.
+      Path to write the test results in HTML format.
     type: string
     default: ''
-  test-results-pdf:
+  code-coverage-cobertura:
     description: >
-      Path to write test results report in PDF format.
+      Path to write the code coverage results in Cobertura XML format.
     type: string
     default: ''
-  no-output-timeout:
+  code-coverage-html:
     description: >
-      Elapsed time the tests can run without output. The string is a decimal with unit suffix,
-      such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the
-      maximum time a job is allowed to run.
+      Path to write the code coverage results in HTML format.
     type: string
-    default: 10m
-  strict:
-    description: >
-      Whether to apply strict checks when running the tests. For example, the command generates a
-      qualification failure if a test issues a warning.
-    type: boolean
-    default: false
-  use-parallel:
-    description: >
-      Whether to run tests in parallel (requires Parallel Computing Toolbox). This feature might
-      not be compatible with certain arguments, in which case, tests run in serial regardless of
-      the specified value.
-    type: boolean
-    default: false
-  output-detail:
+    default: ''
+  model-coverage-cobertura:
     description: >
-      Display level for event details produced by the test run, specified as 'None', 'Terse', 'Concise', 'Detailed', or 'Verbose'.
+      Path to write the model coverage results in Cobertura XML format. This parameter requires a Simulink Coverage license,
+      and is supported in MATLAB R2018b and later.
     type: string
     default: ''
-  logging-level:
+  model-coverage-html:
     description: >
-      Maximum verbosity level for logged diagnostics included for the test run, specified as 'None', 'Terse', 'Concise', 'Detailed', or 'Verbose'.
+      Path to write the model coverage results in HTML format. This parameter requires a Simulink Coverage license, and is
+      supported in MATLAB R2018b and later.
     type: string
     default: ''
+  no-output-timeout:
+    description: >
+      Elapsed time the tests can run without output. The string is a decimal with unit suffix,
+      such as “20m”, “1.25h”, “5s”. The default is 10 minutes and the maximum is governed by the
+      maximum time a job is allowed to run.
+    type: string
+    default: 10m
   startup-options:
     description: >
-      MATLAB startup options. If you specify more than one option, use a space to
-      separate the options.
+      MATLAB startup options, specified as a list of options separated by spaces. For more
+      information about startup options, see
+      https://www.mathworks.com/help/matlab/matlab_env/commonly-used-startup-options.html.
     type: string
     default: ""
 

diff --git a/src/examples/run-build.yml b/src/examples/run-build.yml
@@ -1,5 +1,5 @@
 description: >
-  Run a MATLAB build for your project.
+  Run a build using the MATLAB build tool.
 
 usage:
   version: 2.1
@@ -8,7 +8,7 @@ usage:
   jobs:
     build:
       machine:
-        image: ubuntu-2204:2022.07.1
+        image: ubuntu-2204:2024.01.1
       steps:
         - checkout
         - matlab/install

diff --git a/src/examples/run-custom-script.yml b/src/examples/run-custom-script.yml
@@ -1,5 +1,5 @@
 description: >
-  Run a custom MATLAB script in your project.
+  Run a MATLAB script in your project.
 
 usage:
   version: 2.1
@@ -8,7 +8,7 @@ usage:
   jobs:
     build:
       machine:
-        image: ubuntu-2204:2022.07.1
+        image: ubuntu-2204:2024.01.1
       steps:
         - checkout
         - matlab/install

diff --git a/src/examples/run-tests-with-report.yml b/src/examples/run-tests-with-report.yml
@@ -1,5 +1,5 @@
 description: >
-  Run all tests in your project and produce a test results report.
+  Run all tests in your project and produce test results in JUnit-style XML format.
 
 usage:
   version: 2.1
@@ -8,7 +8,7 @@ usage:
   jobs:
     build:
       machine:
-        image: ubuntu-2204:2022.07.1
+        image: ubuntu-2204:2024.01.1
       steps:
         - checkout
         # Install Simulink and Simulink Test in addition to MATLAB