Clarified package documentation for executor in response to #232

client/executor/exec.go

@@ -1,20 +1,23 @@
-// Package exec is used to invoke child processes across various platforms to
-// provide the following features:
+s// Package executor is used to invoke child processes across various "platforms"
+// in a way that provides the following features:
 //
 // - Least privilege
 // - Resource constraints
 // - Process isolation
 //
-// A "platform" may be defined as coarsely as "Windows" or as specifically as
-// "linux 3.20 with systemd". This allows Nomad to use best-effort, best-
-// available capabilities of each platform to provide resource constraints,
-// process isolation, and security features, or otherwise take advantage of
-// features that are unique to that platform.
+// A "platform" may something like "windows" or "linux with systemd". Executors
+// allow drivers like `exec` and `java` to share a common implementation of the
+// isolation capabilities on a particular operating system.
 //
-// The `semantics of any particular instance are left up to the implementation.
-// However, these should be completely transparent to the calling context. In
-// other words, the Java driver should be able to call exec for any platform and
-// just work.
+// For example:
+//
+// - `exec` and `java` on Linux will use a cgroups executor
+// - `exec` and `java` on FreeBSD will use a jails executor
+//
+// However, drivers that provide their own isolation should not use executors.
+// For example, using an executor to start QEMU means that the QEMU call is
+// run inside a chroot+cgroup, even though the VM already provides isolation for
+// the task running inside it. That's not what we want.
 package executor
 
 import (