Add some scaladocs

Author: ghostbuster91

modules/core/src/main/scala/jsonrpclib/Endpoint.scala

@@ -4,9 +4,28 @@ import io.circe.Decoder
 import io.circe.Encoder
 import jsonrpclib.ErrorCodec.errorPayloadCodec
 
+/** Represents a JSON-RPC method handler that can be invoked by the server.
+  *
+  * An `Endpoint[F]` defines how to decode input from a JSON-RPC message, execute some effectful logic, and optionally
+  * return a response.
+  *
+  * The endpoint's `method` field is used to match incoming JSON-RPC requests.
+  */
 sealed trait Endpoint[F[_]] {
+
+  /** The JSON-RPC method name this endpoint responds to. Used for dispatching incoming requests. */
   def method: String
 
+  /** Transforms the effect type of this endpoint using the provided `PolyFunction`.
+    *
+    * This allows reinterpreting the endpoint’s logic in a different effect context (e.g., from `IO` to `Kleisli[IO,
+    * Ctx, *]`, or from `F` to `EitherT[F, E, *]`).
+    *
+    * @param f
+    *   A polymorphic function that transforms `F[_]` into `G[_]`
+    * @return
+    *   A new `Endpoint[G]` with the same behavior but in a new effect type
+    */
   def mapK[G[_]](f: PolyFunction[F, G]): Endpoint[G]
 }
 

modules/core/src/main/scala/jsonrpclib/PolyFunction.scala

@@ -1,5 +1,12 @@
 package jsonrpclib
 
+/** A polymorphic natural transformation from `F[_]` to `G[_]`.
+  *
+  * @tparam F
+  *   Source effect type
+  * @tparam G
+  *   Target effect type
+  */
 trait PolyFunction[F[_], G[_]] { self =>
   def apply[A0](fa: => F[A0]): G[A0]
 }

modules/fs2/src/main/scala/jsonrpclib/fs2/FS2Channel.scala

@@ -19,6 +19,13 @@ import scala.util.Try
 import _root_.fs2.Pipe
 import _root_.fs2.Stream
 
+/** A JSON-RPC communication channel built on top of `fs2.Stream`.
+  *
+  * `FS2Channel[F]` enables streaming JSON-RPC messages into and out of an effectful system. It provides methods to
+  * register handlers (`Endpoint[F]`) for specific method names.
+  *
+  * This is the primary server-side integration point for using JSON-RPC over FS2.
+  */
 trait FS2Channel[F[_]] extends Channel[F] {
 
   def input: Pipe[F, Message, Unit]
@@ -49,6 +56,20 @@ trait FS2Channel[F[_]] extends Channel[F] {
 
 object FS2Channel {
 
+  /** Creates a new `FS2Channel[F]` as a managed resource with a configurable buffer size for bidirectional message
+    * processing.
+    *
+    * Optionally, a `CancelTemplate` can be provided to support client-initiated cancellation of inflight requests via a
+    * dedicated cancellation endpoint.
+    *
+    * @param bufferSize
+    *   Size of the internal outbound message queue (default: 2048)
+    * @param cancelTemplate
+    *   Optional handler that defines how to decode and handle cancellation requests
+    *
+    * @return
+    *   A `Resource` that manages the lifecycle of the channel and its internal supervisor
+    */
   def resource[F[_]: Concurrent](
       bufferSize: Int = 2048,
       cancelTemplate: Option[CancelTemplate] = None

modules/smithy4s/src/main/scala/jsonrpclib/smithy4sinterop/CirceJsonCodec.scala

@@ -8,6 +8,11 @@ import smithy4s.Schema
 
 object CirceJsonCodec {
 
+  /** Creates a Circe `Codec[A]` from a Smithy4s `Schema[A]`.
+    *
+    * This enables encoding values of type `A` to JSON and decoding JSON back into `A`, using the structure defined by
+    * the Smithy schema.
+    */
   def fromSchema[A](implicit schema: Schema[A]): Codec[A] = Codec.from(
     c => {
       c.as[Json]

modules/smithy4s/src/main/scala/jsonrpclib/smithy4sinterop/ClientStub.scala

@@ -10,6 +10,19 @@ import smithy4s.ShapeId
 
 object ClientStub {
 
+  /** Creates a JSON-RPC client implementation for a Smithy service.
+    *
+    * Given a Smithy `Service[Alg]` and a JSON-RPC communication `Channel[F]`, this constructs a fully functional client
+    * that translates method calls into JSON-RPC messages sent over the channel.
+    *
+    * Usage:
+    * {{{
+    *   val stub: MyService[IO] = ClientStub(myService, myChannel)
+    *   val response: IO[String] = stub.hello("world")
+    * }}}
+    *
+    * Supports both standard request-response and fire-and-forget notification endpoints.
+    */
   def apply[Alg[_[_, _, _, _, _]], F[_]: Monadic](service: Service[Alg], channel: Channel[F]): service.Impl[F] =
     new ClientStub(service, channel).compile
 }

modules/smithy4s/src/main/scala/jsonrpclib/smithy4sinterop/ServerEndpoints.scala

@@ -16,6 +16,19 @@ import _root_.smithy4s.{Endpoint => Smithy4sEndpoint}
 
 object ServerEndpoints {
 
+  /** Creates JSON-RPC server endpoints from a Smithy service implementation.
+    *
+    * Given a Smithy `FunctorAlgebra[Alg, F]`, this extracts all operations and compiles them into JSON-RPC
+    * `Endpoint[F]` handlers that can be mounted on a communication channel (e.g. `FS2Channel`).
+    *
+    * Supports both standard request-response and notification-style endpoints, as well as Smithy-modeled errors.
+    *
+    * Usage:
+    * {{{
+    * val endpoints = ServerEndpoints(new ServerImpl)
+    * channel.withEndpoints(endpoints)
+    * }}}
+    */
   def apply[Alg[_[_, _, _, _, _]], F[_]](
       impl: FunctorAlgebra[Alg, F]
   )(implicit service: Service[Alg], F: Monadic[F]): List[Endpoint[F]] = {
@@ -30,7 +43,21 @@ object ServerEndpoints {
     }
   }
 
-  def jsonRPCEndpoint[F[_]: Monadic, Op[_, _, _, _, _], I, E, O, SI, SO](
+  /** Constructs a JSON-RPC endpoint from a Smithy endpoint definition.
+    *
+    * Translates a single Smithy4s endpoint into a JSON-RPC `Endpoint[F]`, based on the method name and interaction type
+    * described in `EndpointSpec`.
+    *
+    * @param smithy4sEndpoint
+    *   The Smithy4s endpoint to expose over JSON-RPC
+    * @param endpointSpec
+    *   JSON-RPC method name and interaction hints
+    * @param impl
+    *   Interpreter that executes the Smithy operation in `F`
+    * @return
+    *   A JSON-RPC-compatible `Endpoint[F]`
+    */
+  private def jsonRPCEndpoint[F[_]: Monadic, Op[_, _, _, _, _], I, E, O, SI, SO](
       smithy4sEndpoint: Smithy4sEndpoint[Op, I, E, O, SI, SO],
       endpointSpec: EndpointSpec,
       impl: FunctorInterpreter[Op, F]