doc: cleanup

streams/fileStream/README.md

@@ -12,7 +12,7 @@ const fs = new FileStream("/data/logs/logFile.txt");
 ## Specifying the minimum log level
 
 By default, the file stream will log messages at or above `DEBUG`.  You may 
-change this through programmatically setting the minimum log level:
+change this by programmatically setting the minimum log level:
 ```typescript
 const fs = new FileStream("./logFile.txt")
   .withMinLogLevel(Level.ERROR);
@@ -21,18 +21,18 @@ const fs = new FileStream("./logFile.txt")
 
 ## Formatting the log records
 
-The file stream takes in any of Optic's formatters.  See the [full documentation](../..#log-formatting)
+The file stream takes in any of Optic's formatters.  See the [full documentation](https://github.com/onjara/optic#log-formatting)
 on formatting for details.
 
 ## Log buffering
 
-File system writes are comparatively very slow compared to module execution.  To
-reduce this performance hit, log records are buffered (held in memory) until
+File system writes are very slow compared to module execution.  To improve
+log write performance, log records are buffered (held in memory) until
 a threshold is reached at which point the buffered log records are 'flushed' to
 the log file in one go.  This single larger file system access is much more
-efficient than many smaller writes.
+efficient than many smaller writes, resulting in greater module performance.
 
-The default buffer size is 8,192 bytes.  You can also set this value
+The default buffer size is 8,192 bytes.  This value can be set
 programmatically if you want a different buffer size:
 ```typescript
 const fileStream = new FileStream("./logFile.txt")
@@ -42,8 +42,8 @@ const fileStream = new FileStream("./logFile.txt")
 Buffering can also be disabled if desired, thereby forcing immediate writes of
 every log record to the log file, by setting the buffer size to 0 bytes.
 
-There are a number of scenarios where the buffer is flushed:
-* The new log record would exceed the buffer size
+The buffer is flushed in the following scenarios:
+* The new log record, when added to the buffer, would cause the buffer to exceed the max buffer size
 * A log record with a log level greater than `ERROR` is logged
 * The module exits normally (triggering a flush of the buffer via an `unload` event)
 * `flush()` is called manually.  (e.g. `fileStream.flush()`)
@@ -56,9 +56,9 @@ of the log file initialization mode.  There are 3 options:
 
 Option|Description
 ------|-----------
-"append"|Reuse the log file if it exists or create a new one otherwise
-"overwrite"|Always start with an empty log file, overwriting any existing one
-"mustNotExist"|Always start with an empty log file, but throw an error if it already exists
+"append"|Continue appending to an existing log file or create a new empty one if it didn't exist.  This option has no effect on rotated log files.
+"overwrite"|Always start with a clean slate with an empty log file, discarding any existing ones.  In addition to starting with a clean log file, previous rotated log files will also be deleted.
+"mustNotExist"|Always start with an empty log file, but throw an error if it or any previously rotated log files already exists
 
 The log file initialization option is specified via:
 ```typescript
@@ -73,19 +73,21 @@ indefinitely.  You may wish to employ a log rotation strategy.  This will
 automatically move the current log file to a backup file and start a fresh one,
 preventing any individual log file from getting to big.  It can also help
 organize your log files better.  There are two rotation strategies:
-* Byte rotation - When the log file would grow beyond a specified size, then
+* __Byte rotation__ - When the log file would grow beyond a specified size, then
 the file is rotated
-* Date based rotation - This is a work in progress
+* __Date based rotation__ - This is a work in progress
 
 ### Byte size rotation
 
 If a log file write would grow the file bigger than the specified size, then the
 log file is rotated first.  As an example, let's say you have a log file `mod.log`.
-Upon it's first rotation, `mod.log` becomes `mod.log.1` and the log record(s) are
+Upon its first rotation, `mod.log` becomes `mod.log.1` and the log record(s) are
 written to a new, empty, `mod.log`.  When `mod.log` is ready to rotate again,
 `mod.log.1` becomes `mod.log.2`, `mod.log` becomes `mod.log.1` and the new
 record(s) are written to a new, empty, `mod.log`.  The number of log files kept
-in rotation is specified by the rotation strategy.  The default is 7 log files.
+in rotation is specified by the rotation strategy. The default is 7 log files.
+Any log records which fall outside of rotation are deleted.  For example, with
+the default of 7 log files, when mod.log.7 rotates, it would be deleted instead.
 
 Examples:
 ```typescript