Permalink
Browse files

Improved docs

  • Loading branch information...
1 parent f86c3ac commit 31017fce4c2bea862dee96423ba02b5681f24840 @andrewvc committed Jul 25, 2012
Showing with 27 additions and 23 deletions.
  1. +2 −1 .gitignore
  2. +1 −1 project.clj
  3. +24 −21 src/noir_async/core.clj
View
3 .gitignore
@@ -15,4 +15,5 @@ vendor/bundle
pom.xml
.lein-failures
autodoc
-docs
+docs
+target
View
2 project.clj
@@ -1,5 +1,5 @@
(defproject noir-async "1.1.0-beta6"
:description "Async support for noir. Based on Aleph"
- :dependencies [[org.clojure/clojure "1.3.0"]
+ :dependencies [[org.clojure/clojure "1.4.0"]
[noir "1.3.0-beta10"]
[aleph "0.3.0-alpha2"]])
View
45 src/noir_async/core.clj
@@ -16,7 +16,7 @@
(or response-channel request-channel))
(defn regular?
- "Is this a regular HTTP connection? I.E. Not a websocket"
+ "true if this is a regular HTTP connection, I.E. not a websocket."
[conn]
(= :regular (:type conn)))
@@ -27,30 +27,35 @@
@(:chunked-initiated? conn)))
(defn one-shot?
- "Is this connection able a oneshot response?"
+ "true if the connection is able to send a oneshot response, I.E. not chunked or a websocket."
[conn]
(and (regular? conn) (not (chunked? conn))))
(defn websocket?
- "Is the connection opened from the client as a websocket?"
+ "True if the connection was is a websocket"
[conn]
(= :websocket (:type conn)))
(defn closed?
- "Is this connection closed?"
+ "Returns true if the connection is already closed"
[conn]
(lc/closed? (:request-channel conn)))
-(defn- writable-channel
- "Returns the a connections writable channel."
+(defn writable-channel
+ "Returns the connection's writable channel. Useful if you need to directly pipe using lamina."
[{:keys [request-channel response-channel] :as conn}]
(cond (websocket? conn) request-channel
(regular? conn) (if (chunked? conn) @response-channel request-channel)
:else nil))
+(defn readable-channel
+ "Returns the connection's readable channel. Useful if you need to directly pipe using lamina."
+ [{:keys [request-channel]}]
+ request-channel)
+
(defn async-push-header
- "Explicitly sends a chunked header, the same as
- (async-push conn {:chunked true})"
+ "Explicitly sends a chunked header. Should not be used directly, instead use (async-push {:chunked true})."
+ {:no-doc true}
[conn header-map]
(when (not (map? header-map))
(throw "Expected a map of header options!"))
@@ -66,10 +71,11 @@
(lc/enqueue (:request-channel conn) resp)))
(defn async-push
- "Pushes data to the client.
+ "This should be the only method you need to send data.
+ All pushes to the client through this are asynchronous.
If it's a websocket this sends a message.
- If it's a normal connection, it sends an entire response in one shot.
- To start a multi-part connection, send a header with the body set to :chunked
+ If it's a normal connection, it sends the entire response in one shot and closes the connection.
+ To start a multi-part connection, send a header with the the option :chunked set to true
ex: (async-push conn {:chunked true})
If this is a multipart connection (a chunked header has been sent been called earlier) this sends a new body chunk."
[conn data]
@@ -84,7 +90,7 @@
(af/bytes->string (:body (:ring-request conn))))
(defn request-body-byte-buffer
- "Retrieves the request body as a byte[]"
+ "Retrieves the request body as a ByteBuffer"
[conn]
(af/bytes->byte-buffer (:body (:ring-request conn))))
@@ -97,8 +103,7 @@
(when (lc/channel? req-ch) (lc/close req-ch))))
(defn on-close
- "Sets a callback to handle a closed connection.
- Callback takes no arguments."
+ "Sets a callback to handle a closed connection. Callback takes no arguments."
[{:keys [request-channel response-channel]} handler]
(if (lc/channel? request-channel)
(lc/on-closed request-channel handler)
@@ -115,8 +120,8 @@
(lc/on-realized request-channel handler nil)))
(defn connection
- "Generates a new map representing a connection.
- Generally for internal use only."
+ "Generates a new map representing a connection."
+ {:no-doc true}
[request-channel ring-request]
{:request-channel request-channel
:ring-request ring-request
@@ -125,9 +130,8 @@
:type (if (:websocket ring-request) :websocket :regular) })
(defmacro defaleph-handler
- "Returns an fn suitable for raw use with aleph + a ring request.
- Works much like defpage-async, just with fewer bindings. Look
- at the docs for defpage-async for more details."
+ "Returns an fn suitable for raw use with aleph + a ring request. Generally it is preferred to use defpage-async"
+ {:no-doc true}
[conn-binding & body]
`(fn na-aleph-handle-inner [ch# ring-request#]
(let [~conn-binding (connection ch# ring-request#)]
@@ -138,8 +142,7 @@
(defmacro defpage-async
"Creates an asynchronous noir route. This route can handle both
regular HTTP and Websocket connections. For regular HTTP
- responses can be delivered in one shot, or in chunked mode.
-"
+ responses can be delivered in one shot, or in chunked mode."
[route request-bindings conn-binding & body]
`(nc/custom-handler ~route {~request-bindings :params}
(ah/wrap-aleph-handler

0 comments on commit 31017fc

Please sign in to comment.