Docs

Author: jamesdbrock

src/Node/HTTP2.purs

@@ -94,25 +94,25 @@
 -- | but we want to wait until they’ve all completed before we continue.
 -- |
 -- | ```
--- |   parSequence_
--- |     [ operation1
--- |     , operation2
--- |     , operation3
--- |     ]
+-- | parSequence_
+-- |   [ operation1
+-- |   , operation2
+-- |   , operation3
+-- |   ]
 -- | ```
 -- |
 -- | We can also use do-blocks in this idiom. And collect the results
 -- | if the results are all some interesting type instead of `Unit`.
 -- |
 -- | ```
--- |   [result1, result2, result3] <- parSequence
--- |     [ do
--- |         operation1
--- |     , do
--- |         operation2
--- |     , do
--- |         operation3
--- |     ]
+-- | [result1, result2, result3] <- parSequence
+-- |   [ do
+-- |       operation1
+-- |   , do
+-- |       operation2
+-- |   , do
+-- |       operation3
+-- |   ]
 -- | ```
 -- |
 -- | #### Aff Idiom: Concurrent effects with heterogeneous return values
@@ -137,6 +137,20 @@
 -- |       operation3
 -- | ```
 -- |
+-- | #### Aff Idiom: Surprising events
+-- |
+-- | We have `event1`, `event2`, and `event3`, which are
+-- | all side-effecting `Aff Unit` operations. We know one of them
+-- | will complete next, but we don’t know which one. We want to wait for
+-- | all of them at the same time.
+-- |
+-- | ```
+-- | parOneOf
+-- |   [ event1
+-- |   , event2
+-- |   , event3
+-- |   ]
+-- | ```
 module Node.HTTP2
   ( HeadersObject(..)
   , toHeaders

src/Node/HTTP2/Client.purs

@@ -89,28 +89,55 @@ close :: ClientHttp2Session -> Effect Unit -> Effect Unit
 close = unsafeCoerce Internal.close
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-response
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 foreign import onceResponse :: ClientHttp2Stream -> (HeadersObject -> Flags -> Effect Unit) -> Effect (Effect Unit)
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-headers
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 foreign import onceHeaders :: ClientHttp2Stream -> (HeadersObject -> Flags -> Effect Unit) -> Effect (Effect Unit)
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-stream
 -- |
 -- | https://nodejs.org/docs/latest/api/http2.html#push-streams-on-the-client
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceStream :: ClientHttp2Session -> (ClientHttp2Stream -> HeadersObject -> Flags -> Effect Unit) -> Effect (Effect Unit)
 onceStream = unsafeCoerce Internal.onceStream
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-stream
 -- |
 -- | https://nodejs.org/docs/latest/api/http2.html#push-streams-on-the-client
+-- |
+-- | Returns an effect for removing the event listener.
 onStream :: ClientHttp2Session -> (ClientHttp2Stream -> HeadersObject -> Flags -> Effect Unit) -> Effect (Effect Unit)
 onStream = unsafeCoerce Internal.onStream
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-error
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceErrorSession :: ClientHttp2Session -> (Error -> Effect Unit) -> Effect (Effect Unit)
 onceErrorSession = unsafeCoerce Internal.onceEmitterError
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-error_1
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceErrorStream :: ClientHttp2Stream -> (Error -> Effect Unit) -> Effect (Effect Unit)
 onceErrorStream = unsafeCoerce Internal.onceError
 
@@ -120,14 +147,26 @@ onceErrorStream = unsafeCoerce Internal.onceError
 foreign import oncePush :: ClientHttp2Stream -> (HeadersObject -> Flags -> Effect Unit) -> Effect (Effect Unit)
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-trailers
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceTrailers :: ClientHttp2Stream -> (HeadersObject -> Flags -> Effect Unit) -> Effect (Effect Unit)
 onceTrailers = unsafeCoerce Internal.onceTrailers
 
 -- | https://nodejs.org/docs/latest/api/stream.html#event-data
+-- |
+-- | Returns an effect for removing the event listener.
 onData :: ClientHttp2Stream -> (Buffer -> Effect Unit) -> Effect (Effect Unit)
 onData = unsafeCoerce Internal.onData
 
 -- | https://nodejs.org/docs/latest/api/net.html#event-end
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceEnd :: ClientHttp2Stream -> Effect Unit -> Effect (Effect Unit)
 onceEnd = unsafeCoerce Internal.onceEnd
 

src/Node/HTTP2/Server.Aff.purs

@@ -60,14 +60,6 @@ import Web.Fetch.AbortController as Web.Fetch.AbortController
 -- |
 -- | The argument is the `createServer` options.
 -- | See [`http2.createServer([options][, onRequestHandler])`](https://nodejs.org/docs/latest/api/http2.html#http2createserveroptions-onrequesthandler)
--- |
--- | Example:
--- |
--- | ```
--- | server <- createServer $ unsafeToForeign
--- |   {
--- |   }
--- | ```
 createServer
   :: OptionsObject
   -> Aff Http2Server
@@ -136,6 +128,11 @@ listen server options handler = makeAff \complete -> do
     Web.Fetch.AbortController.abort abortcontroller
 
 -- | Create a secure (HTTPS) HTTP/2 server.
+-- |
+-- | The argument is the `createServer` options.
+-- | See [`http2.createServer([options][, onRequestHandler])`](https://nodejs.org/docs/latest/api/http2.html#http2createserveroptions-onrequesthandler)
+-- |
+-- | Required options: `key :: String`, `cert :: String`.
 createSecureServer
   :: OptionsObject
   -> Aff Http2SecureServer

src/Node/HTTP2/Server.purs

@@ -84,6 +84,11 @@ closeServer :: Http2Server -> Effect Unit -> Effect Unit
 closeServer = unsafeCoerce Internal.close
 
 -- | https://nodejs.org/docs/latest/api/net.html#event-close
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceCloseServer :: Http2Server -> Effect Unit -> Effect (Effect Unit)
 onceCloseServer = unsafeCoerce Internal.onceServerClose
 
@@ -106,24 +111,27 @@ closeServerSecure :: Http2SecureServer -> Effect Unit -> Effect Unit
 closeServerSecure = unsafeCoerce Internal.close
 
 -- | https://nodejs.org/docs/latest/api/net.html#event-close
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceCloseServerSecure :: Http2SecureServer -> Effect Unit -> Effect (Effect Unit)
 onceCloseServerSecure = unsafeCoerce Internal.onceServerClose
 
 -- | https://nodejs.org/docs/latest/api/net.html#event-error
 -- |
 -- |  the 'close' event will not be emitted directly following this event unless server.close() is manually called.
 -- |
--- | Returns an effect for removing the event listener before the event
--- | is raised.
+-- | Returns an effect for removing the event listener.
 onErrorServer :: Http2Server -> (Error -> Effect Unit) -> Effect (Effect Unit)
 onErrorServer = unsafeCoerce Internal.onEmitterError
 
 -- | https://nodejs.org/docs/latest/api/net.html#event-error
 -- |
 -- |  the 'close' event will not be emitted directly following this event unless server.close() is manually called.
 -- |
--- | Returns an effect for removing the event listener before the event
--- | is raised.
+-- | Returns an effect for removing the event listener.
 onErrorServerSecure :: Http2SecureServer -> (Error -> Effect Unit) -> Effect (Effect Unit)
 onErrorServerSecure = unsafeCoerce Internal.onEmitterError
 
@@ -139,6 +147,12 @@ onErrorServerSecure = unsafeCoerce Internal.onEmitterError
 foreign import data ServerHttp2Session :: Type
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-session
+-- |
+-- | Listen for one event, call the callback, then remove
+-- | the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 foreign import onceSession :: Http2Server -> (ServerHttp2Session -> Effect Unit) -> Effect Unit
 
 -- | https://nodejs.org/docs/latest/api/http2.html#http2sessionclosecallback
@@ -156,11 +170,14 @@ onceStream :: Http2Server -> (ServerHttp2Stream -> HeadersObject -> Flags -> Eff
 onceStream = unsafeCoerce Internal.onceStream
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-stream
+-- |
+-- | Returns an effect for removing the event listener.
 onStream :: Http2Server -> (ServerHttp2Stream -> HeadersObject -> Flags -> Effect Unit) -> Effect (Effect Unit)
 onStream = unsafeCoerce Internal.onStream
 
 -- | Listen for one event, call the callback, then remove
 -- | the event listener.
+-- |
 -- | Returns an effect for removing the event listener before the event
 -- | is raised.
 -- |
@@ -169,6 +186,8 @@ onceStreamSecure :: Http2SecureServer -> (ServerHttp2Stream -> HeadersObject ->
 onceStreamSecure = unsafeCoerce Internal.onceStream
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-stream
+-- |
+-- | Returns an effect for removing the event listener.
 onStreamSecure :: Http2SecureServer -> (ServerHttp2Stream -> HeadersObject -> Flags -> Effect Unit) -> Effect (Effect Unit)
 onStreamSecure = unsafeCoerce Internal.onStream
 
@@ -177,6 +196,11 @@ respond :: ServerHttp2Stream -> HeadersObject -> OptionsObject -> Effect Unit
 respond = unsafeCoerce Internal.respond
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-session_1
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceSessionSecure :: Http2SecureServer -> (ServerHttp2Session -> Effect Unit) -> Effect Unit
 onceSessionSecure = unsafeCoerce onceSession
 
@@ -199,6 +223,11 @@ foreign import pushAllowed :: ServerHttp2Stream -> Effect Boolean
 foreign import additionalHeaders :: ServerHttp2Stream -> HeadersObject -> Effect Unit
 
 -- | https://nodejs.org/docs/latest/api/http2.html#event-wanttrailers
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceWantTrailers :: ServerHttp2Stream -> Effect Unit -> Effect (Effect Unit)
 onceWantTrailers = unsafeCoerce Internal.onceWantTrailers
 
@@ -209,6 +238,11 @@ sendTrailers :: ServerHttp2Stream -> HeadersObject -> Effect Unit
 sendTrailers = unsafeCoerce Internal.sendTrailers
 
 -- | https://nodejs.org/docs/latest/api/net.html#event-end
+-- |
+-- | Listen for one event, then remove the event listener.
+-- |
+-- | Returns an effect for removing the event listener before the event
+-- | is raised.
 onceEnd :: ServerHttp2Stream -> Effect Unit -> Effect (Effect Unit)
 onceEnd = unsafeCoerce Internal.onceEnd