Improve documentation

README.md

@@ -3,19 +3,13 @@
 [![Package Version](https://img.shields.io/hexpm/v/finch_gleam)](https://hex.pm/packages/finch_gleam)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/finch_gleam/)
 
-A Gleam project
+A wrapper/adapter package for the [Finch](https://hexdocs.pm/finch) HTTP client.
 
-## Quick start
-
-```sh
-gleam run   # Run the project
-gleam test  # Run the tests
-gleam shell # Run an Erlang shell
-```
+This library adapts the Finch functions to accept and return [gleam/http](https://hexdocs.pm/gleam_http) requests and responses.
 
 ## Installation
 
-If available on Hex this package can be added to your Gleam project:
+This package can be added to your Gleam project:
 
 ```sh
 gleam add finch_gleam

gleam.toml

@@ -1,12 +1,13 @@
 name = "finch_gleam"
 version = "1.0.0"
+target = "erlang"
 
 # Fill out these fields if you intend to generate HTML documentation or publish
 # your project to the Hex package manager.
 
 licences = ["MIT"]
 description = "Gleam wrapper for the Finch HTTP client"
-repository = { type = "gitlab", user = "Nicd", repo = "gleam_finch" }
+repository = { type = "gitlab", user = "Nicd", repo = "finch_gleam" }
 links = []
 
 [dependencies]

src/finch.gleam

@@ -1,6 +1,7 @@
-//// A wrapper module for the Finch HTTP client
+//// Finch API wrapper module.
 ////
-//// https://hexdocs.pm/finch
+//// See the [Finch documentation](https://hexdocs.pm/finch) for additional
+//// information about the functions.
 
 import gleam
 import gleam/uri
@@ -12,7 +13,8 @@ import finch/headers.{Headers}
 import finch/stream.{StreamFun}
 import finch/otp.{InstanceOptions, OnStart}
 
-pub type Method {
+// Finch's HTTP method type
+type Method {
   Head
   Get
   Put
@@ -30,15 +32,15 @@ pub type RequestOption {
 pub type RequestOptions =
   List(RequestOption)
 
-/// Finch request, use `build/2` to create one from a Gleam request
+/// Finch request, use `build/2` to create one from a Gleam request.
 pub external type Request
 
 external type Response
 
-/// Exception returned by Finch in case of request errors
+/// Exception returned by Finch in case of request errors.
 pub external type Exception
 
-/// Build a Finch request that can be run with `request/2` or `stream/5`
+/// Build a Finch request that can be run with `request/2` or `stream/5`.
 ///
 /// Note, the HTTP methods CONNECT, TRACE, and `Other(String)` are not
 /// supported, and will be converted to GET.
@@ -69,7 +71,7 @@ external fn build_ext(
 ) -> Request =
   "Elixir.Finch" "build"
 
-/// Send a request using the Finch server with the given name
+/// Send a request using the Finch instance with the given name.
 pub fn request(
   req: Request,
   name: Atom,
@@ -86,7 +88,7 @@ pub fn request(
 external fn do_request(req: Request, name: Atom) -> Result(Response, Exception) =
   "Elixir.Finch" "request"
 
-/// Stream a request using the Finch server with the given name
+/// Stream a request using the Finch instance with the given name.
 pub external fn stream(
   req: Request,
   name: Atom,
@@ -96,7 +98,7 @@ pub external fn stream(
 ) -> Result(a, Exception) =
   "Elixir.Finch" "stream"
 
-/// Start a new Finch server with the given options
+/// Start a new Finch instance with the given options.
 pub external fn start_link(opts: InstanceOptions) -> OnStart =
   "Elixir.Finch" "start_link"
 

src/finch/otp.gleam

@@ -1,4 +1,4 @@
-//// Types related to OTP usage of Finch
+//// Types related to OTP usage of Finch.
 
 import gleam/uri
 import gleam/dynamic.{Dynamic}
@@ -48,6 +48,10 @@ pub type InstanceOption {
 pub type InstanceOptions =
   List(InstanceOption)
 
+/// Returned by `start_link/2`.
+///
+/// Note that this is not the same as Gleam's standard `Result` type! You will
+/// need to match this manually, it cannot be used with `try` syntax.
 pub type OnStart {
   Ok(child: Pid)
   Ignore

src/finch/stream.gleam

@@ -1,10 +1,15 @@
 import finch/headers.{Headers as ReqHeaders}
 
+/// A block of data sent by Finch from the HTTP request stream.
 pub type StreamBlock {
   Status(status: Int)
   Headers(headers: ReqHeaders)
   Data(data: BitString)
 }
 
+/// A stream handler function
+///
+/// Receives a block of the stream data as the first argument and the
+/// accumulator as the second, must return the accumulator.
 pub type StreamFun(a) =
   fn(StreamBlock, a) -> a

src/finch/timeout.gleam

@@ -1,19 +1,20 @@
-//// Wrapper of Elixir's `timeout/0` type
+//// Wrapper of Elixir's `timeout/0` type.
 ////
-//// See https://hexdocs.pm/elixir/typespecs.html#built-in-types
+//// See [https://hexdocs.pm/elixir/typespecs.html#built-in-types](https://hexdocs.pm/elixir/typespecs.html#built-in-types)
+//// for a specification of the type.
 
 import gleam/dynamic
 
-/// A timeout value, either infinite or a specified amount of milliseconds
+/// A timeout value, either infinite or a specified amount of milliseconds.
 pub external type Timeout
 
-/// Create an infinite timeout
+/// Create an infinite timeout.
 pub fn infinity() -> Timeout {
   dynamic.from(Infinity)
   |> dynamic.unsafe_coerce()
 }
 
-/// Create a timeout with the given milliseconds
+/// Create a timeout with the given milliseconds.
 pub fn milliseconds(ms: Int) -> Timeout {
   dynamic.from(ms)
   |> dynamic.unsafe_coerce()