Doc the :connection option, which is a discouraged, advanced option […

…IMMUTANT-327]

docs/src/org/messaging.org

@@ -439,8 +439,18 @@
          (publish somewhere msg)))
    #+end_src
 
-
+   It's also possible to manage connections yourself and use them by
+   setting the =:connection= option, but of course you're then
+   responsible for starting and closing them when you're done. Here's
+   an example:
 
+   #+begin_src clojure
+     (with-open [c (immutant.messaging.core/create-connection {})]
+       (.start c)
+       (with-connection {:connection c}
+         (publish wherever whatever)))
+   #+end_src
+
 ** A word about performance
 
    Though HornetQ is [[https://community.jboss.org/wiki/HornetQ-thePerformanceLeaderinEnterpriseMessaging][capable of being very fast]], Immutant's default

modules/messaging/src/main/clojure/immutant/messaging.clj

@@ -92,7 +92,8 @@
      :username        the username to use to auth the connection (requires :password
                       to be set) [nil]
      :password        the password to use to auth the connection (requires :username
-                      to be set) [nil]"
+                      to be set) [nil]
+     :connection      a JMS Connection to use; caller expected to close [nil]"
   [dest message & {:as opts}]
   (with-connection opts
     (let [opts (options opts)
@@ -129,7 +130,8 @@
      :username   the username to use to auth the connection (requires :password to
                  be set) [nil]
      :password   the password to use to auth the connection (requires :username to
-                 be set) [nil]"
+                 be set) [nil]
+     :connection a JMS Connection to use; caller expected to close [nil]"
   [dest & {:as opts}]
   (with-connection opts
     (let [opts (options opts)