docs(taskfiles): Add guidelines for writing docstrings for tasks. (#27)

docs/dev-guide/contrib-guides-taskfiles.md

@@ -278,5 +278,34 @@ my-task:
     - "lib2"
 ```
 
+## Task docstrings
+
+For reusable utility tasks that take arguments, you should add a docstring above the task definition
+using a JSDoc-like syntax. The following example demonstrates the syntax:
+
+```yaml
+# Task description including a description of any side effects or outputs generated by this task.
+#
+# @param {param_type} PARAM_1 Description for a required parameter.
+# @param {param_type} [PARAM_2] Description for an optional parameter.
+# @param {param_type} [PARAM_3=default_value] Description for an optional parameter with a default
+# value.
+# @param {[]param_type} PARAM_4 Description for a required parameter that's an array.
+# @param {map[key_type]value_type} PARAM_5 Description for a required parameter that's a map.
+```
+
+* The task's description (and the empty line following it) may be omitted if the task's name makes
+  it obvious.
+* Each parameter's description may be omitted if it's obvious (however, the tag, type, and name
+  should always be present).
+* Each parameter's type should use Go's (rather than JavaScript's) syntax for specifying types.
+
+:::{note}
+Tasks have an optional [`desc`][task-attrs] attribute that technically serves the same purpose as
+the task description in the docstring. However, the description in the docstring can be easier to
+format, and we should avoid fragmenting the docstring. Thus, we recommend against using `desc` when
+a docstring is present.
+:::
+
 [Taskfiles]: https://taskfile.dev/usage/
-[task-attrs]: https://taskfile.dev/api/#task
+[task-attrs]: https://taskfile.dev/reference/schema#task