Updated docs with more accurate upstream-closing behavior

Author: KingMob

doc/stream.md

@@ -118,7 +118,7 @@ true
 
 Here, we create a source stream `s`, and map `inc` and `dec` over it.  When we put our message into `s` it immediately is accepted, since `a` and `b` are downstream.  All messages put into `s` will be propagated into *both* `a` and `b`.
 
-If `s` is closed, both `a` and `b` will be closed, as will any other downstream sources we've created.  Likewise, if everything downstream of `s` is closed, `s` will also be closed.  This is almost always desirable, as failing to do this will simply cause `s` to exert backpressure on everything upstream of it.  However, If we wish to avoid this behavior, we can create a `(permanent-stream)`, which cannot be closed.
+If `s` is closed, both `a` and `b` will be closed, as will any other downstream sources we've created.  Likewise, if everything downstream of `s` is closed, `s` will also be closed, once it's unable to `put!` anywhere.  This is almost always desirable, as failing to do this will simply cause `s` to exert backpressure on everything upstream of it.  However, if we wish to avoid this behavior, we can create a stream using `stream*` and `:permanent? true`, which cannot be closed.
 
 For any Clojure operation that doesn't have an equivalent in `manifold.stream`, we can use `manifold.stream/transform` with a transducer:
 

src/manifold/stream.clj

@@ -305,10 +305,10 @@
    Optionally takes a map of parameters:
 
    |:---|:---
-   | `upstream?` | if closing the sink should always close the source, even if there are other sinks downstream of the source.  Defaults to `false`.  Note that if the sink is the only thing downstream of the source, the source will always be closed, unless it is permanent.
-   | `downstream?` | if closing the source will close the sink.  Defaults to `true`.
-   | `timeout` | if defined, the maximum time, in milliseconds, that will be spent trying to put a message into the sink before closing it.  Useful when there are multiple sinks downstream of a source, and you want to avoid a single backed up sink from blocking all the others.
-   | `description` | describes the connection, useful for traversing the stream topology via `downstream`."
+   | `upstream?` | Whether closing the sink should always close the source, even if there are other sinks downstream of the source.  Defaults to `false`.  Note that if the sink is the only thing downstream of the source, the source will eventually be closed, unless it is permanent.
+   | `downstream?` | Whether closing the source will close the sink.  Defaults to `true`.
+   | `timeout` | If defined, the maximum time, in milliseconds, that will be spent trying to put a message into the sink before closing it.  Useful when there are multiple sinks downstream of a source, and you want to avoid a single backed-up sink from blocking all the others.
+   | `description` | Describes the connection, useful for traversing the stream topology via `downstream`."
   {:arglists
    '[[source sink]
      [source
@@ -336,7 +336,7 @@
 
 (defn stream
   "Returns a Manifold stream with a configurable `buffer-size`.  If a capacity is specified,
-   `put!` will yield `true` when the message is in the buffer.  Otherwise it will only yield
+   `put!` will yield `true` when the message is in the buffer.  Otherwise, it will only yield
    `true` once it has been consumed.
 
    `xform` is an optional transducer, which will transform all messages that are enqueued