Skip to content

Commit 34febc1

Browse files
committed
Standardize formatting of task parameter documentation
Some tasks accept input via environment variables. These parameter variables are documented in the task description. A standard format has been established for that documentation. Previously, these descriptions did not follow the standardized format. Typically, the documentation is done in the task description, to make the information easily accessible to contributors via the `task list` output. However, a description was intentionally omitted for these tasks. The reason is these tasks are for internal use by other tasks, only serving to avoid code duplication. So the tasks should not be listed in the `task list` output. Task actually has a feature for marking such tasks as internal, but unfortunately that only works for the standard way of calling a task from another task, which can not be used in this case where the output of the task must be captured. For this reason, the task documentation is intentionally done via a comment instead of the description as would be done for a contributor facing task.
1 parent db6a442 commit 34febc1

File tree

2 files changed

+12
-4
lines changed

2 files changed

+12
-4
lines changed

Taskfile.yml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1018,7 +1018,9 @@ tasks:
10181018
fi
10191019
- shfmt -w "{{.SCRIPT_PATH}}"
10201020

1021-
# Make a temporary file named according to the passed TEMPLATE variable and print the path passed to stdout
1021+
# Make a temporary file and print the path passed to stdout.
1022+
# Environment variable parameters:
1023+
# - TEMPLATE: template for the format of the filename.
10221024
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
10231025
utility:mktemp-file:
10241026
vars:
@@ -1039,7 +1041,9 @@ tasks:
10391041
vars:
10401042
RAW_PATH: "{{.RAW_PATH}}"
10411043

1042-
# Print a normalized version of the path passed via the RAW_PATH variable to stdout
1044+
# Print a normalized version of the path to stdout.
1045+
# Environment variable parameters:
1046+
# - RAW_PATH: the path to be normalized.
10431047
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
10441048
utility:normalize-path:
10451049
cmds:

workflow-templates/assets/windows-task/Taskfile.yml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22
version: "3"
33

44
tasks:
5-
# Make a temporary file named according to the passed TEMPLATE variable and print the path passed to stdout
5+
# Make a temporary file and print the path passed to stdout.
6+
# Environment variable parameters:
7+
# - TEMPLATE: template for the format of the filename.
68
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
79
utility:mktemp-file:
810
vars:
@@ -13,7 +15,9 @@ tasks:
1315
vars:
1416
RAW_PATH: "{{.RAW_PATH}}"
1517

16-
# Print a normalized version of the path passed via the RAW_PATH variable to stdout
18+
# Print a normalized version of the path to stdout.
19+
# Environment variable parameters:
20+
# - RAW_PATH: the path to be normalized.
1721
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
1822
utility:normalize-path:
1923
cmds:

0 commit comments

Comments
 (0)