Skip to content

Commit a29f6f5

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 c3b5a33 commit a29f6f5

File tree

1 file changed

+6
-2
lines changed

1 file changed

+6
-2
lines changed

Taskfile.yml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -717,7 +717,9 @@ tasks:
717717
fi
718718
- shfmt -w "{{.SCRIPT_PATH}}"
719719

720-
# Make a temporary file named according to the passed TEMPLATE variable and print the path passed to stdout
720+
# Make a temporary file and print the path passed to stdout.
721+
# Environment variable parameters:
722+
# - TEMPLATE: template for the format of the filename.
721723
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
722724
utility:mktemp-file:
723725
vars:
@@ -739,7 +741,9 @@ tasks:
739741
vars:
740742
RAW_PATH: "{{.RAW_PATH}}"
741743

742-
# Print a normalized version of the path passed via the RAW_PATH variable to stdout
744+
# Print a normalized version of the path to stdout.
745+
# Environment variable parameters:
746+
# - RAW_PATH: the path to be normalized.
743747
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
744748
utility:normalize-path:
745749
cmds:

0 commit comments

Comments
 (0)