docs

API.md

@@ -40,13 +40,13 @@ The `fs.Stats` of the file.
 
 ### `bytes`
 
-The file's contents can be updated by getting or setting `bytes`, which is a `Buffer`.
+The file's contents can be retrieved and updated by getting or setting `bytes`, which is a `Buffer`.
 
 Don't mutate this property. This causes various unwanted effects. Instead, assign it a new `Buffer` instance.
 
 ### `text`
 
-The file's contents can also be updated by getting or setting `text`, which is a string.
+The file's contents can also be retrieved and updated by getting or setting `text`, which is a string.
 
 Reassigning the entire `bytes` or `text` properties will keep the other in sync.
 
@@ -65,13 +65,13 @@ A new `Defiler` instance to represent a collection of physical files and virtual
 - Directory configuration
 	- `dir` - the directory to watch
 	- `read` - _(optional)_ whether to actually read in the contents of the files in the directory. Defaults to `true`. If `false`, the files will still be run through the transform, but they will have null `bytes` and `text`
-	- `enc` - _(optional)_ encoding to use for files read in from the directory. Defaults to `'utf8'`. This can also be changed for individual files (see [`enc`](#enc))
+	- `enc` - _(optional)_ encoding to use for files read in from the directory. Defaults to `'utf8'`. This can also be changed for individual files (see [`file.enc`](#enc))
 	- `watch` - _(optional)_ whether to actually watch the directory for changes. Defaults to `true`. If `false`, the files will still be run through the transform, but any changes to them will not be
 	- `debounce` - _(optional)_ The length of the timeout in milliseconds to use to debounce incoming events from `fs.watch`. Defaults to 10. Multiple events are often emitted for a single change, and events can also be emitted before `fs.stat` reports the changes. Defiler will wait until `debounce` milliseconds have passed since the last `fs.watch` event for a file before handling it. The default of 10ms Works On My Machine
 - Transform configuration
 	- `transform({ defiler, file })` - a transform function, which is passed an object containing the `Defiler` instance and the `File` instance to mutate. The transform function can return a `Promise` to indicate when it's done
 - Generator configuration
-	- `generators` - an array of generator functions, each of the form `generator({ defiler })`. Each generator is passed an object containing the `Defiler` instance. Each generator function can return a `Promise` to indicate when it's done
+	- `generators` - _(optional)_ an array of generator functions, each of the form `generator({ defiler })`. Each generator is passed an object containing the `Defiler` instance. Each generator function can return a `Promise` to indicate when it's done
 
 ## Properties
 
@@ -101,7 +101,7 @@ Returns a `Promise` resolving to the `File` instance or an array of `File` insta
 
 This can be asked for physical or virtual files. If you ask for a file during the initial wave of processing before it is available, Defiler will wait for the file to be ready and transformed. If it ever happens that every in-progress file is waiting for a file to become available, the deadlock will be broken by Defiler resolving all of the pending `File`s to `undefined`. This may happen multiple times during the initial wave of processing.
 
-When used in your transform, this will also register the file being transformed as depending on the file or files in `path`. Once the initial wave of processing is complete, any changes to dependencies will cause their dependents to be re-transformed. When used in a generator, this will register the generator as depending on the file on files in `path`, and any changes to dependencies will cause the generator to be re-run.
+When used in your transform, this will also register the file being transformed as depending on the file or files in `path`. Once the initial wave of processing is complete, any changes to dependencies will cause their dependents to be re-transformed. When used in a generator, this will register the generator as depending on the file or files in `path`, and any changes to dependencies will cause the generator to be re-run.
 
 ### `add(file)`
 

GUIDE.md

@@ -40,6 +40,14 @@ Generators are an independent way of interacting with the Defiler instance, for
 
 It's beneficial to write multiple smaller generators, rather than a single large one. This helps ensure that unneeded recalculation is not done when a file changes.
 
+## Waves
+
+Processing in Defiler happens in waves, sort of. During the first wave, all files have the transform run on them, all generators are run, and any virtual files added with `defiler.add` are also transformed. It's at the end of this first wave that the `Promise` returned by [`defiler.exec()`](API.md#exec) resolves. Subsequently, each change to a watched file results in another wave, during which all dependent files are re-transformed, all dependent generators are re-run, and all added virtual files are re-transformed. If any watched file changes come in while a wave is still active, a new wave will be started immediately upon the completion of the previous one. Otherwise, a new wave will be started when a new file change event comes in.
+
+It's only during the first wave that the special deadlock resolution behavior is relevant. On subsequent waves, any missing files requested via [`defiler.get(path)`](API.md#getpath) will return (a `Promise` resolving to) `undefined`. This does, however, establish a dependence relation between the two, and if the missing file ever does exist later (either as a physical or virtual file), the dependent file/generator will be re-transformed/re-run.
+
+When performing production builds, you probably only want to have a first wave, and to not watch for subsequent file changes. This can be achieved with the [`watch` option to the `Defiler` constructor](API.md#defiler).
+
 # Usage
 
 First, [create a new `Defiler` instance](API.md#defiler), initializing it with the directory to watch, the transform, and the generators.