HADOOP-13327 review of more of Sean Busbey's comments

TODO "Could this be in a section about visibility and not in the model definition? Maybe later. "here's the model, here's how that model works with creation, here's how it works when reading/writing" flows much better and visibility should be in that third part."

Change-Id: I61c89475a1ea72006524803f2a7dd9e40551d718

Author: steveloughran

hadoop-common-project/hadoop-common/src/site/markdown/filesystem/filesystem.md

@@ -623,6 +623,8 @@ The updated (valid) FileSystem must contains all the parent directories of the p
 The result is `FSDataOutputStream`, which through its operations may generate new filesystem states with updated values of
 `FS.Files[p]`
 
+The behavior of the returned stream is covered in [Output](outputstream.html).
+
 #### Implementation Notes
 
 * Some implementations split the create into a check for the file existing
@@ -654,6 +656,8 @@ this precondition fails.
 
 Make a `FSDataOutputStreamBuilder` to specify the parameters to create a file.
 
+The behavior of the returned stream is covered in [Output](outputstream.html).
+
 #### Implementation Notes
 
 `createFile(p)` returns a `FSDataOutputStreamBuilder` only and does not make
@@ -685,11 +689,15 @@ Implementations without a compliant call SHOULD throw `UnsupportedOperationExcep
 Return: `FSDataOutputStream`, which can update the entry `FS.Files[p]`
 by appending data to the existing list.
 
+The behavior of the returned stream is covered in [Output](outputstream.html).
+
 ### `FSDataOutputStreamBuilder appendFile(Path p)`
 
 Make a `FSDataOutputStreamBuilder` to specify the parameters to append to an
 existing file.
 
+The behavior of the returned stream is covered in [Output](outputstream.html).
+
 #### Implementation Notes
 
 `appendFile(p)` returns a `FSDataOutputStreamBuilder` only and does not make

hadoop-common-project/hadoop-common/src/site/markdown/filesystem/outputstream.md

@@ -97,13 +97,13 @@ FS'.Files(path) == buffer
 ```
 
 Any client reading the data at the path MUST see the new data.
-The two sync operations, `hflush()` and `hsync()` differ in their durability
+The `Syncable` operations differ in their durability
 guarantees, not visibility of data.
 
-### State of Stream and Filesystem after `Filesystem.create()`
+### State of Stream and File System after `Filesystem.create()`
 
 The output stream returned by a `FileSystem.create(path)` or
-`FileSystem.createFile(path).build`
+`FileSystem.createFile(path).build()` within a filesystem `FS`,
 can be modeled as a triple containing an empty array of no data:
 
 ```python
@@ -113,7 +113,7 @@ Stream' = (path, true, [])
 The filesystem `FS'` MUST contain a 0-byte file at the path:
 
 ```python
-data(FS', path) == []
+FS' = FS where data(FS', path) == []
 ```
 
 Thus, the initial state of `Stream'.buffer` is implicitly
@@ -122,10 +122,10 @@ consistent with the data at the filesystem.
 
 *Object Stores*: see caveats in the "Object Stores" section below.
 
-### State of Stream and Filesystem after `Filesystem.append()`
+### State of Stream and File System after `Filesystem.append()`
 
 The output stream returned from a call of
- `FileSystem.append(path, buffersize, progress)`,
+ `FileSystem.append(path, buffersize, progress)` within a filesystem `FS`,
 can be modelled as a stream whose `buffer` is intialized to that of
 the original file:
 
@@ -149,7 +149,7 @@ After a call to `close()`, the stream is closed for all operations other
 than `close()`; they MAY fail with `IOException` or `RuntimeException`.
 
 ```python
-Stream' =  (path, false, [])
+Stream' = (path, false, [])
 ```
 
 The `close()` operation MUST be idempotent with the sole attempt to write the