Improve docs

lib/frankt.ex

@@ -1,13 +1,15 @@
 defmodule Frankt do
   @moduledoc """
-  Trigger client-side commands from the server.
+  Run client-side actions from the backend.
 
-  Frankt allows you to define websocket responses that will trigger commands in the clients.
-  Responses run on the server and leverage all the Elixir and Phoenix capabilities. A thin JS layer
-  applies the desired commands in the clients.
+  Frankt provides a thin layer over Phoenix Channels which allows running client-side actions
+  from the backend. Since the logic of those actions lives in the backend, they can leverage all the
+  `Elixir` and `Phoenix` capabilities.
 
   ## Usage
 
+  Frankt modules are actually `Phoenix.Channel` modules with some extra functionality.
+
   Frankt modules must define responses that are triggered by client-side actions.
 
   ```

lib/frankt/plug.ex

@@ -1,8 +1,13 @@
 defmodule Frankt.Plug do
   @moduledoc """
-  Defines the required callbacks for Frankt plugs.
+  The Frankt plug specification.
+
+  Frankt plugs must export a `call/2` function which receives the socket and a
+  set of options and returns a socket.
+
+  For concrete examples of Frankt plugs, you can take a look at the
+  `Frankt.Plug.SetHandler`, `Frankt.Plug.SetGettext` and `Frankt.Plug.ExecuteAction`.
   """
-  @type opts :: binary | tuple | atom | integer | float | [opts] | %{opts => opts}
 
-  @callback call(socket :: Phoenix.Socket.t(), opts :: opts) :: Phoenix.Socket.t()
+  @callback call(socket :: Phoenix.Socket.t(), opts :: Plug.opts()) :: Phoenix.Socket.t()
 end

lib/frankt/plug/execute_action.ex

@@ -1,22 +1,25 @@
+# Runs the action handler for the incoming Frankt action.
+
 defmodule Frankt.Plug.ExecuteAction do
-  @moduledoc """
-  Runs the user handler for the incoming Frankt action.
-  """
+  @moduledoc false
   @behaviour Frankt.Plug
 
   alias Frankt.ConfigurationError
 
+  @impl true
   def call(socket = %{private: %{frankt_gettext: nil}}, _opts) do
     invoke_action(socket)
   end
 
+  @impl true
   def call(socket = %{private: %{frankt_gettext: gettext}, assigns: %{locale: locale}}, _opts)
       when is_binary(locale) or is_atom(locale) do
     Gettext.with_locale(gettext, locale, fn ->
       invoke_action(socket)
     end)
   end
 
+  @impl true
   def call(%{private: %{frankt_module: frankt_module}}, _opts) do
     raise ConfigurationError,
       module: frankt_module,

lib/frankt/plug/set_gettext.ex

@@ -1,11 +1,11 @@
-defmodule Frankt.Plug.SetGettext do
-  @moduledoc """
-  Sets the Frankt gettext information for the incoming action.
+# Sets the Frankt gettext information for the incoming action.
+# The gettext module is stored under the `frankt_module` key in the socket.
 
-  The gettext module is stored under the `frankt_module` key in the socket.
-  """
+defmodule Frankt.Plug.SetGettext do
+  @moduledoc false
   @behaviour Frankt.Plug
 
+  @impl true
   def call(socket = %{private: private = %{frankt_module: frankt_module}}, _opts) do
     gettext_module = frankt_module.gettext()
     %{socket | private: Map.put(private, :frankt_gettext, gettext_module)}

lib/frankt/plug/set_handler.ex

@@ -1,14 +1,15 @@
-defmodule Frankt.Plug.SetHandler do
-  @moduledoc """
-  Sets the Frankt handler information for the incoming action.
+# Sets the Frankt handler information for the incoming action.
+# The handler is stored under the `frankt_handler` key in the form of a
+# `{handler_module, handler_fn}` tuple.
 
-  The handler is stored under the `frankt_handler` key in the form of a
-  `{handler_module, handler_fn}` tuple.
-  """
+defmodule Frankt.Plug.SetHandler do
+  @moduledoc false
   @behaviour Frankt.Plug
 
   alias Frankt.ConfigurationError
 
+  @impl true
+  @doc false
   def call(socket = %{private: %{frankt_action: action} = private}, _opts) do
     [handler_name, handler_fn] = String.split(action, ":")
     handler = {handler(socket, handler_name), String.to_existing_atom(handler_fn)}

lib/frankt/test/action_test.ex

@@ -1,27 +1,23 @@
 defmodule Frankt.ActionTest do
   @moduledoc """
   Conveniences for testing Frankt actions.
+  You can `import Frankt.ActionTest` in your test cases having easy access to the helpers provided
+  by this module.
 
-  Frankt tests are actually channel tests. For more information take a look at
-  `Phoenix.ChannelTest`.
+  Frankt tests are channel tests, so the same helpers and principles apply. For more information
+  take a look at `Phoenix.ChannelTest`.
   """
 
-  @doc false
-  defmacro __using__(_opts) do
-    quote do
-      import Frankt.ActionTest
-    end
-  end
-
   @doc """
-  Call a Frankt action.
+  Invoke a Frankt action.
 
-  Pushes a mesasge into the channel which triggers the Frankt `handle_in/3` function and then
-  dispatches to the corresponding action.
-  After pushing the message to Frankt you can check the response by using
+  Underneath, this function pushes a message into the Frankt channel so it can be dispatched by the
+  corresponding action.
+  After the message is pushed into the Frankt channel, you can check the response by using
   `Phoenix.ChannelTest.assert_push/3`.
   """
-  @spec frankt_action(socket :: Socket.t(), action :: String.t(), payload :: map()) :: reference()
+  @spec frankt_action(socket :: Phoenix.Socket.t(), action :: String.t(), payload :: map()) ::
+          reference()
   defmacro frankt_action(socket, action, payload \\ %{}) do
     quote do
       push(unquote(socket), "frankt-action", %{action: unquote(action), data: unquote(payload)})

mix.exs

@@ -49,6 +49,7 @@ defmodule Frankt.Mixfile do
         "guides/Concepts.md": [],
         "guides/Examples.md": []
       ],
+      groups_for_modules: [Testing: [Frankt.ActionTest]],
       main: "README.md"
     ]
   end

test/support/channel_case.ex

@@ -7,7 +7,8 @@ defmodule Frankt.ChannelCase do
     quote do
       # Import conveniences for testing with channels
       use Phoenix.ChannelTest
-      use Frankt.ActionTest
+
+      import Frankt.ActionTest
 
       # The default endpoint for testing
       @endpoint Frankt.TestApplication.Endpoint