Improvement suggestion: document await that it will never return if shutdown-agents was called

[Ruslan Al-Fakikh]

Hi guys,

This is my first post here and I'm new to Clojure, so excuse me if anything is wrong.

I would like to submit a patch to fix the docstring for clojure.core/await from this:
...Will never return if
a failed agent is restarted with :clear-actions true.
to this
...Will never return if
a failed agent is restarted with :clear-actions true or shutdown-agents was called.

This was a surprise to me to find yet another condition when await never returns. Here is the proof:
(def my-agent (agent 0))

(defn sleep-and-inc [number]
(Thread/sleep 3000)
(println "action number" number "complete")
(inc number))

(println "sending off 2 times")
(send-off my-agent sleep-and-inc)
(send-off my-agent sleep-and-inc)
(println "sending off complete")

;making sure all the actions have completed to make it simple,
;otherwise only the first action will be executed
(Thread/sleep 7000)

(shutdown-agents)

(println "starting await")
(await my-agent)
(println "await complete");this will never happen

;here is how it behaves:
;sending off 2 times
;sending off complete
;action number 0 complete
;action number 1 complete
;starting await
;...hanging forever...

Let me guys know if this is a good improvement that is worth patching. I'd love to submit this patch!

Thanks,
Ruslan Al-Fakikh