Merge pull request finagle#158 from finagle/endpoint-for-routers

Update scaladoc. Add endpoint for routers

core/src/main/scala/io/finch/package.scala

@@ -26,21 +26,68 @@ import com.twitter.finagle.httpx.path.Path
 
 import scala.language.implicitConversions
 
-import com.twitter.finagle.httpx._
+import com.twitter.finagle.httpx
 import com.twitter.util.Future
 import com.twitter.finagle.{Filter, Service}
 
 /**
- * The root package of the Finch library.
+ * This is a root package of the Finch library, which provides an immutable
+ * layer of functions and types atop of Finagle for writing lightweight consuming
+ * HTTP services. It roughly contains three packages: [[io.finch.route]],
+ * [[io.finch.request]], [[io.finch.response]], which correspond to three simple
+ * steps to a robust REST/HTTP API:
  *
- * <p/>
+ * Step 1. Routing the HTTP request to a [[Service]].
  *
- * See details at https://github.com/finagle/finch.
+ * The [[io.finch.route.Router]] abstraction routes the requests depending on their
+ * path and method information. `Router` combinator provides a bunch of predefined
+ * routers handling separated parts of a route. `Router`s might be composed with
+ * either `/` (`flatMap`) or `/>` (`map`) operator. There is also `|` (`orElse`)
+ * operator that combines two routers in terms of the inclusive or operator.
+ *
+ * {{{
+ *   val router: Endpoint[HttpRequest, HttpResponse] =
+ *     Get / ("users" | "user") / int /> GetUser
+ * }}}
+ *
+ * Step 2: Reading the HTTP request in a [[Service]].
+ *
+ * The [[io.finch.request.RequestReader]] abstraction is responsible for reading
+ * any details form the HTTP request. `RequestReader` is composable in both ways:
+ * via the monadic API (using the for-comprehension, i.e., `flatMap`/`map`) and via
+ * the applicative API (using the `~` operator). These approaches define an unlimited
+ * number of readers out the plenty of predefined ones.
+ *
+ * {{{
+ *   val pagination: RequestReader[(Int, Int)] =
+ *     OptionalIntParam("offset") ~ OptionalIntParam("limit") map {
+ *       case offset ~ limit => (offset.getOrElse(0), limit.getOrElse(100))
+ *     }
+ *   val p = pagination(request)
+ * }}}
+ *
+ * Step 3. Building the HTTP response in a [[Service]].
+ *
+ * The [[io.finch.response.ResponseBuilder]] abstraction provides a convenient way
+ * of building the HTTP responses any type. In fact, `ResponseBuilder` is a function
+ * that takes some content and builds an HTTP response of a type depending on a content.
+ * There are plenty of predefined builders that might be used directly.
+ *
+ * {{{
+ *   val ok: HttpResponse = Ok("Hello, world!") // plain/text HTTP response with status code 200
+ * }}}
  */
 package object finch {
 
-  type HttpRequest = Request
-  type HttpResponse = Response
+  /**
+   * An alias for [[httpx.Request]].
+   */
+  type HttpRequest = httpx.Request
+
+  /**
+   * An alias for [[httpx.Response]].
+   */
+  type HttpResponse = httpx.Response
 
   /**
    * Alters any object within a ''toFuture'' method.

core/src/main/scala/io/finch/route/package.scala

@@ -35,9 +35,9 @@ import com.twitter.util.Future
  * of the rest of the route. `RouterN[A]` (or just `Router[A]`) in addition
  * to the `Router0` behaviour extracts a value of type `A` from the route.
  *
- * A [[route.Router]] that extracts [[Service]] is called an endpoint. An
- * endpoint `Req => Rep` might be implicitly converted into `Service[Req, Rep]`.
- * Thus, the following example is a valid Finch code:
+ * A [[route.Router]] that maps route to a [[Service]] is called an
+ * [[route.Endpoint]]. An endpoint `Req => Rep` might be implicitly converted
+ * into `Service[Req, Rep]`. Thus, the following example is a valid Finch code:
  *
  * {{{
  *   def hello(s: String) = new Service[HttRequest, HttpResponse] {
@@ -76,6 +76,11 @@ package object route {
    */
   type Router[+A] = RouterN[A]
 
+  /**
+   * An alias for [[Router]] that maps route to a [[Service]].
+   */
+  type Endpoint[-A, +B] = Router[Service[A, B]]
+
   /**
    * An exception, which is thrown by router in case of missing route `r`.
    */