docs: Update doc comments; rename the run and execute APIs `names…

…` argument to `taskNames`; update README.

README.md

@@ -11,7 +11,7 @@ for [Deno](https://deno.land/) inspired by
 - File tasks and non-file tasks.
 - Drake API functions for defining, registering and running tasks.
 
-**Status**: Tested with Deno 1.3.2 running on Ubuntu 20.04, Windows 10. See
+**Status**: Tested with Deno 1.3.3 running on Ubuntu 20.04, Windows 10. See
 [releases](https://github.com/srackham/drake/blob/master/releases.md).
 
 
@@ -362,10 +362,12 @@ if (!env("--quiet")) console.log(message);
 
 ### execute
 ``` typescript
-async function execute(...names: string[]);
+async function execute(...taskNames: string[]);
 ```
 
-Unconditionally execute task action functions asynchronously.
+Execute task action functions.
+The non-async actions are executed synchronously then the
+async actions are exectuted asynchronously.
 Silently skip tasks that have no action function.
 
 ### glob
@@ -414,11 +416,11 @@ Read the entire contents of a file synchronously to a UTF-8 string.
 
 ### run
 ``` typescript
-async function run(...names: string[]);
+async function run(...taskNames: string[]);
 ```
 
 Execute named tasks along with their prerequisite tasks (direct and
-indirect). If no `names` are specified then the command-line tasks
+indirect). If no task names are specified then the command-line tasks
 are run. If no command-line tasks were specified the default task is
 run (specified by setting the `env` API `"--default-task"` value).
 

lib/registry.ts

@@ -31,47 +31,50 @@ export function task(name: string, prereqs?: string[], action?: Action): Task {
 
 /**
  * Execute named tasks along with their prerequisite tasks (direct and
- * indirect). If no `names` are specified then the command-line tasks are run.
+ * indirect). If no task names are specified then the command-line tasks are run.
  * If no command-line tasks were specified the default task (set in
  * `env("--default-task")`) is run.
  *
  * Task execution is ordered such that prerequisite tasks are executed prior to
  * their parent task. The same task is never run twice.
  */
-export async function run(...names: string[]) {
+export async function run(...taskNames: string[]) {
   if (env("--help") || env("--version")) {
     return;
   }
   if (env("--list-tasks") || env("--list-all")) {
     taskRegistry.list().forEach((t: unknown) => console.log(t));
   } else {
-    if (names.length === 0) {
-      names = env("--tasks");
-      if (names.length === 0 && env("--default-task")) {
-        names.push(env("--default-task"));
+    if (taskNames.length === 0) {
+      taskNames = env("--tasks");
+      if (taskNames.length === 0 && env("--default-task")) {
+        taskNames.push(env("--default-task"));
       }
     }
-    if (names.length === 0) {
+    if (taskNames.length === 0) {
       abort(
         "no task specified (use the --list-tasks option to list tasks, --help for help)",
       );
     }
     isRunning = true;
     try {
-      await taskRegistry.run(...names);
+      await taskRegistry.run(...taskNames);
     } finally {
       isRunning = false;
     }
   }
 }
 
 /**
- * Execute task action functions asynchronously.
+ * Execute task action functions.
+ * The non-async actions are executed synchronously then the
+ * async actions are exectuted asynchronously.
  * Silently skip tasks that have no action function.
  */
-export async function execute(...names: string[]) {
+export async function execute(...taskNames: string[]) {
   if (!isRunning) {
+    // Necessary because the `run` API ensures the Drake cache file is saved.
     abort("'execute' API must be called by 'run' API");
   }
-  await taskRegistry.execute(...names);
+  await taskRegistry.execute(...taskNames);
 }

lib/tasks.ts

@@ -388,7 +388,9 @@ export class TaskRegistry extends Map<string, Task> {
   }
 
   /**
-   * Execute task action functions asynchronously.
+   * Execute task action functions.
+   * The non-async actions are executed synchronously then the
+   * async actions are exectuted asynchronously.
    * Silently skip tasks that have no action function.
    */
   async execute(...names: string[]) {