Improve docs across the project

.gitignore

@@ -1,5 +1,6 @@
-/_build
-/deps
+/_build/
+/deps/
 erl_crash.dump
 *.ez
 /doc
+/tmp/

README.md

@@ -3,7 +3,7 @@
 ![CI Status](https://github.com/lexmag/msgpax/workflows/CI/badge.svg)
 [![Hex Version](https://img.shields.io/hexpm/v/msgpax.svg)](https://hex.pm/packages/msgpax)
 
-This library provides an API for serializing and de-serializing Elixir terms using the [MessagePack](http://msgpack.org/) format.
+This library provides an API for serializing and deserializing Elixir terms using the [MessagePack](http://msgpack.org/) format.
 
 [Documentation is available online][docs].
 

lib/msgpax.ex

@@ -1,12 +1,12 @@
 defmodule Msgpax do
   @moduledoc ~S"""
-  This module provides functions for serializing and de-serializing Elixir terms
+  This module provides functions for serializing and deserializing Elixir terms
   using the [MessagePack](http://msgpack.org/) format.
 
   ## Data conversion
 
   The following table shows how Elixir types are serialized to MessagePack types
-  and how MessagePack types are de-serialized back to Elixir types.
+  and how MessagePack types are deserialized back to Elixir types.
 
   Elixir                            | MessagePack   | Elixir
   --------------------------------- | ------------- | -------------
@@ -20,7 +20,7 @@ defmodule Msgpax do
   *N/A*<sup>1</sup>                 | -infinity     | `Msgpax.NegInfinity`<sup>2</sup>
   `:ok`                             | string        | `"ok"`
   `Atom`                            | string        | `"Elixir.Atom"`
-  `"str"`                           | string        | `"str"`
+  `"text"`                          | string        | `"text"`
   `"\xFF\xFF"`                      | string        | `"\xFF\xFF"`
   `#Msgpax.Bin<"\xFF">`             | binary        | `"\xFF"`<sup>3</sup>
   `%{foo: "bar"}`                   | map           | `%{"foo" => "bar"}`
@@ -40,7 +40,7 @@ defmodule Msgpax do
   alias __MODULE__.Unpacker
 
   @doc """
-  Serializes `term`.
+  Serializes the given `term`.
 
   This function returns iodata by default; if you want to force the result to be
   a binary, you can use `IO.iodata_to_binary/1` or use the `:iodata` option (see
@@ -126,12 +126,12 @@ defmodule Msgpax do
   end
 
   @doc """
-  De-serializes part of the given `iodata`.
+  Deserializes part of the given `iodata`.
 
   This function works like `unpack/2`, but instead of requiring the input to be
   a MessagePack-serialized term with nothing after that, it accepts leftover
-  bytes at the end of `iodata` and only de-serializes the part of the input that
-  makes sense. It returns `{:ok, term, rest}` if de-serialization is successful,
+  bytes at the end of `iodata` and only deserializes the part of the input that
+  makes sense. It returns `{:ok, term, rest}` if deserialization is successful,
   `{:error, exception}` otherwise (where `exception` is a `Msgpax.UnpackError`
   struct).
 
@@ -165,7 +165,7 @@ defmodule Msgpax do
   Works like `unpack_slice/2` but raises in case of error.
 
   This function works like `unpack_slice/2`, but returns just `{term, rest}` if
-  de-serialization is successful and raises a `Msgpax.UnpackError` exception if
+  deserialization is successful and raises a `Msgpax.UnpackError` exception if
   it's not.
 
   ## Examples
@@ -189,10 +189,10 @@ defmodule Msgpax do
   end
 
   @doc """
-  De-serializes the given `iodata`.
+  Deserializes the given `iodata`.
 
-  This function de-serializes the given `iodata` into an Elixir term. It returns
-  `{:ok, term}` if the de-serialization is successful, `{:error, exception}`
+  This function deserializes the given `iodata` into an Elixir term. It returns
+  `{:ok, term}` if the deserialization is successful, `{:error, exception}`
   otherwise, where `exception` is a `Msgpax.UnpackError` struct which can be
   raised or converted to a more human-friendly error message with
   `Exception.message/1`. See `Msgpax.UnpackError` for all the possible reasons
@@ -242,7 +242,7 @@ defmodule Msgpax do
   Works like `unpack/2`, but raises in case of errors.
 
   This function works like `unpack/2`, but it returns `term` (instead of `{:ok,
-  term}`) if de-serialization is successful, otherwise raises a
+  term}`) if deserialization is successful, otherwise raises a
   `Msgpax.UnpackError` exception.
 
   ## Example

lib/msgpax/bin.ex

@@ -3,17 +3,15 @@ defmodule Msgpax.Bin do
   A struct to represent the MessagePack [Binary
   type](https://github.com/msgpack/msgpack/blob/master/spec.md#formats-bin).
 
-  Elixir binaries are serialized and de-serialized as [MessagePack
+  Elixir binaries are serialized and deserialized as [MessagePack
   strings](https://github.com/msgpack/msgpack/blob/master/spec.md#formats-str):
   `Msgpax.Bin` is used when you want to enforce the serialization of a binary
-  into the Binary MessagePack type. De-serialization functions (such as
+  into the Binary MessagePack type. Deserialization functions (such as
   `Msgpax.unpack/2`) provide an option to deserialize Binary terms (which are
-  de-serialized to Elixir binaries by default) to `Msgpax.Bin` structs.
+  deserialized to Elixir binaries by default) to `Msgpax.Bin` structs.
   """
 
-  @type t :: %__MODULE__{
-          data: binary
-        }
+  @type t :: %__MODULE__{data: binary}
 
   defstruct [:data]
 

lib/msgpax/ext.ex

@@ -6,15 +6,15 @@ defmodule Msgpax.Ext do
   ## Examples
 
   Let's say we want to be able to serialize a custom type that consists of a
-  byte `data` repeated `reps` times. We could represent this as a `RepByte`
+  byte `data` repeated `count` times. We could represent this as a `RepByte`
   struct in Elixir:
 
       defmodule RepByte do
-        defstruct [:data, :reps]
+        defstruct [:data, :count]
       end
 
   A simple (albeit not space efficient) approach to encoding such data is simply
-  a binary containing `data` for `reps` times: `%RepByte{data: ?a, reps: 2}`
+  a binary containing `data` for `count` times: `%RepByte{data: ?a, count: 2}`
   would be encoded as `"aa"`.
 
   We can now define the `Msgpax.Packer` protocol for the `RepByte` struct to
@@ -24,16 +24,16 @@ defmodule Msgpax.Ext do
       defimpl Msgpax.Packer, for: RepByte do
         @rep_byte_ext_type 10
 
-        def pack(%RepByte{data: b, reps: reps}) do
+        def pack(%RepByte{data: byte, count: count}) do
           @rep_byte_ext_type
-          |> Msgpax.Ext.new(String.duplicate(<<b>>, reps))
+          |> Msgpax.Ext.new(String.duplicate(<<byte>>, count))
           |> Msgpax.Packer.pack()
         end
       end
 
   Now, we can pack `RepByte`s:
 
-      iex> packed = Msgpax.pack!(%RepByte{data: ?a, reps: 3})
+      iex> packed = Msgpax.pack!(%RepByte{data: ?a, count: 3})
       iex> Msgpax.unpack!(packed)
       #Msgpax.Ext<10, "aaa">
 
@@ -54,26 +54,24 @@ defmodule Msgpax.Ext do
         @behaviour Msgpax.Ext.Unpacker
         @rep_byte_ext_type 10
 
+        @impl true
         def unpack(%Msgpax.Ext{type: @rep_byte_ext_type, data: data}) do
           <<byte, _rest::binary>> = data
-          {:ok, %RepByte{data: byte, reps: byte_size(data)}}
+          {:ok, %RepByte{data: byte, count: byte_size(data)}}
         end
       end
 
   With this in place, we can now unpack a packed `RepByte` back to a `RepByte`
   struct:
 
-      iex> packed = Msgpax.pack!(%RepByte{data: ?a, reps: 3})
+      iex> packed = Msgpax.pack!(%RepByte{data: ?a, count: 3})
       iex> Msgpax.unpack!(packed, ext: MyExtUnpacker)
-      %RepByte{data: ?a, reps: 3}
+      %RepByte{data: ?a, count: 3}
 
   """
 
   @type type :: 0..127
-  @type t :: %__MODULE__{
-          type: type,
-          data: binary
-        }
+  @type t :: %__MODULE__{type: type, data: binary}
 
   defstruct [:type, :data]
 

lib/msgpax/ext/reserved_ext.ex → lib/msgpax/reserved_ext.ex

@@ -2,7 +2,8 @@ defimpl Msgpax.Packer, for: DateTime do
   use Bitwise
 
   def pack(datetime) do
-    Msgpax.ReservedExt.new(-1, build_data(datetime))
+    -1
+    |> Msgpax.ReservedExt.new(build_data(datetime))
     |> @protocol.Msgpax.ReservedExt.pack()
   end
 
@@ -26,25 +27,27 @@ defimpl Msgpax.Packer, for: DateTime do
 end
 
 defmodule Msgpax.ReservedExt do
-  @moduledoc false
+  @moduledoc """
+  Reserved extensions automatically get handled by Msgpax.
+  """
 
   @behaviour Msgpax.Ext.Unpacker
 
   @nanosecond_range -62_167_219_200_000_000_000..253_402_300_799_999_999_999
 
-  @type type :: -128..-1
-  @type t :: %__MODULE__{
-          type: type,
-          data: binary
-        }
+  @typep type :: -128..-1
+  @opaque t :: %__MODULE__{type: type, data: binary}
 
   defstruct [:type, :data]
 
+  @doc false
   def new(type, data)
       when type in -128..-1 and is_binary(data) do
     %__MODULE__{type: type, data: data}
   end
 
+  @doc false
+  @impl true
   def unpack(%__MODULE__{type: -1, data: data}) do
     case data do
       <<seconds::32>> ->

lib/msgpax/unpacker.ex

@@ -1,6 +1,6 @@
 defmodule Msgpax.UnpackError do
   @moduledoc """
-  Raised when there's an error in de-serializing some data into an Elixir term.
+  Raised when there's an error in deserializing some data into an Elixir term.
   """
 
   @type t :: %__MODULE__{

mix.exs

@@ -25,7 +25,7 @@ defmodule Msgpax.Mixfile do
 
   defp description() do
     "This library provides an API for serializing" <>
-      " and de-serializing Elixir terms using the MessagePack format."
+      " and deserializing Elixir terms using the MessagePack format."
   end
 
   defp package() do