refactor: improve and document handler type inference (#18)

* refactor: improve and document handler type inference

* fix: clippy and tests

* docs: more info in the handler docs

* doc: fix em

* doc: nits

* docs: slight improvements

Cargo.toml

@@ -5,7 +5,7 @@ description = "Simple, modern, ergonomic JSON-RPC 2.0 router built with tower an
 keywords = ["json-rpc", "jsonrpc", "json"]
 categories = ["web-programming::http-server", "web-programming::websocket"]
 
-version = "0.1.2"
+version = "0.2.0"
 edition = "2021"
 rust-version = "1.81"
 authors = ["init4", "James Prestwich"]

src/lib.rs

@@ -12,15 +12,16 @@
 //! ```no_run
 //! use ajj::{Router, HandlerCtx, ResponsePayload};
 //!
-//! # fn main() {
+//! # fn test_fn() -> Router<()> {
 //! // Provide methods called "double" and "add" to the router.
 //! let router = Router::<u64>::new()
-//!   .route("double", |params: u64| async move {
-//!     Ok::<_, ()>(params * 2)
-//!   })
 //!   .route("add", |params: u64, state: u64| async move {
 //!     Ok::<_, ()>(params + state)
 //!   })
+//!   .with_state(3u64)
+//!   .route("double", |params: u64| async move {
+//!     Ok::<_, ()>(params * 2)
+//!   })
 //!   // Routes get a ctx, which can be used to send notifications.
 //!   .route("notify", |ctx: HandlerCtx| async move {
 //!     if ctx.notifications().is_none() {
@@ -43,9 +44,8 @@
 //!   .route("error_example", || async {
 //!     // This will appear in the ResponsePayload's `message` field.
 //!     ResponsePayload::<(), ()>::internal_error_message("this is an error".into())
-//!   })
-//!   // The router is provided with state, and is now ready to serve requests.
-//!   .with_state::<()>(3u64);
+//!   });
+//! # router
 //! # }
 //! ```
 //!
@@ -144,7 +144,9 @@ pub mod pubsub;
 pub use pubsub::ReadJsonStream;
 
 mod routes;
-pub use routes::{BatchFuture, Handler, HandlerArgs, HandlerCtx, NotifyError, RouteFuture};
+pub use routes::{
+    BatchFuture, Handler, HandlerArgs, HandlerCtx, NotifyError, Params, RouteFuture, State,
+};
 pub(crate) use routes::{BoxedIntoRoute, ErasedIntoRoute, Method, Route};
 
 mod router;

src/router.rs

@@ -33,26 +33,25 @@ use tracing::{debug_span, trace};
 /// The `double` method doubles the provided number, and the `add` method adds
 /// the provided number to some state, and returns the sum.
 ///
-/// These methods can
-///
 /// ```
-/// use ajj::{Router};
+/// use ajj::Router;
 ///
 /// # fn main() {
 /// // Provide methods called "double" and "add" to the router.
 /// let router = Router::<u64>::new()
-///   .route("double", |params: u64| async move {
-///     Ok::<_, ()>(params * 2)
-///   })
+///    // This route requires state to be provided.
 ///   .route("add", |params: u64, state: u64| async move {
 ///     Ok::<_, ()>(params + state)
 ///   })
-///   // The router is provided with state, and is now ready to serve requests.
-///   .with_state::<()>(3u64);
+///   .with_state::<()>(3u64)
+///   // when double is called, the provided number is doubled.
+///   // see the Handler docs for more information on the hint type
+///   .route("double", |params: u64| async move {
+///     Ok::<_, ()>(params * 2)
+///   });
 /// # }
 /// ```
 ///
-///
 /// ## Note
 ///
 /// The state `S` is "missing" state. It is state that must be added to the

src/routes/future.rs

@@ -13,10 +13,9 @@ use tower::util::{BoxCloneSyncService, Oneshot};
 
 use super::Response;
 
-/// A future produced by [`Router::call_with_state`]. This should only be
-/// instantiated by that method.
+/// A future produced by the [`Router`].
 ///
-/// [`Route`]: crate::routes::Route
+/// [`Router`]: crate::Router
 #[pin_project]
 pub struct RouteFuture {
     /// The inner [`Route`] future.
@@ -159,7 +158,9 @@ impl BatchFuture {
     }
 
     /// Push a parse result into the batch. Convenience function to simplify
-    /// [`Router::call_batch_with_state`] logic.
+    /// [`Router`] logic.
+    ///
+    /// [`Router`]: crate::Router
     pub(crate) fn push_parse_result(&mut self, result: Result<RouteFuture, RequestError>) {
         match result {
             Ok(fut) => self.push(fut),