More work

README.md

@@ -2,3 +2,5 @@
 
 JSON-RPC crate using async/await.
 Designed to be the successor to [ParityTech's JSONRPC crate](https://github.com/paritytech/jsonrpc/).
+
+Use `cargo doc` to generate the documentation of this crate.

core/src/server/batches.rs

@@ -339,6 +339,7 @@ mod tests {
             .request_by_id(rq_id)
             .unwrap()
             .set_response(Err(common::Error::method_not_found()));
+        assert!(state.request_by_id(rq_id).is_none());
 
         match state.next_event() {
             Some(BatchesEvent::ReadyToSend {

core/src/server/server.rs

@@ -33,6 +33,10 @@ pub struct Server<R, I> {
     /// that are using it.
     ///
     /// If this reaches 0, we can tell the raw server to close the request.
+    ///
+    /// Because we don't have any information about `I`, we have to use a collision-resistant
+    /// hashing algorithm. This incurs a performance cost that is theoretically avoidable (if `I`
+    /// is always local), but that should be negligible in practice.
     num_subscriptions: HashMap<I, NonZeroUsize>,
 }
 
@@ -230,6 +234,11 @@ where
     ///   sent out.
     /// - Otherwise, this response is buffered.
     ///
+    /// > **Note**: This method is implemented in a way that doesn't wait for long to send the
+    /// >           response. While calling this method will block your entire server, it
+    /// >           should only block it for a short amount of time. See also [the equivalent
+    /// >           method](crate::RawServer::finish) on the [`RawServer`](crate::RawServer) trait.
+    ///
     pub async fn respond(self, response: Result<common::JsonValue, common::Error>) {
         self.inner.set_response(response);
         //unimplemented!();

proc-macros/src/lib.rs

@@ -6,8 +6,39 @@ use quote::quote;
 
 mod api_def;
 
-/// Test doc
-// TODO: ^
+/// Wraps around one or more API definitions and generates an enum.
+///
+/// The format within this macro must be:
+///
+/// ```ignore
+/// rpc_api!{
+///     Foo { ... }
+///     pub(crate) Bar { ... }
+/// }
+/// ```
+///
+/// The `Foo` and `Bar` are identifiers, optionally prefixed with a visibility modifier
+/// (e.g. `pub`).
+///
+/// The content of the blocks is the same as the content of a trait definition, except that
+/// default implementations for methods are forbidden.
+///
+/// For each identifier (such as `Foo` and `Bar` in the example above), this macro will generate
+/// an enum where each variant corresponds to a function of the definition. Function names are
+/// turned into PascalCase to conform to the Rust style guide.
+/// 
+/// Each generated enum has a `next_request` method whose signature is:
+///
+/// ```ignore
+/// async fn next_request(server: &'a mut jsonrpsee::core::Server<R, I>) -> Result<Foo<'a, R, I>, std::io::Error>;
+/// ```
+/// 
+/// This method lets you grab the next request incoming from a server, and parse it to match of
+/// the function definitions. Invalid requests are automatically handled.
+///
+/// Additionally, each generated enum has one method per function definition that lets you perform
+/// the method has a client.
+///
 #[proc_macro]
 pub fn rpc_api(input_token_stream: TokenStream) -> TokenStream {
     // Start by parsing the input into what we expect.