Improve docs (#16)

* Add autogenerated docs * Add typedocs * Add docs for into_* functions * Improve docs * Add Application verb * Remove dead links
YodelTalk · Dec 18, 2023 · adf643d · adf643d
1 parent 330a3d4
commit adf643d
Show file tree

Hide file tree

Showing 5 changed files with 166 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![Test](https://github.com/YodelTalk/twiml/actions/workflows/test.yml/badge.svg)](https://github.com/YodelTalk/twiml/actions/workflows/test.yml)
 [![CI](https://github.com/YodelTalk/twiml/actions/workflows/ci.yml/badge.svg)](https://github.com/YodelTalk/twiml/actions/workflows/ci.yml)
 
-TwiML is a Elixir library to generate complex TwiML responses for Twilio in an
+TwiML is a Elixir library to generate complex TwiML documents for Twilio in an
 elegant way.
 
 <!-- MDOC !-->

diff --git a/lib/twiml.ex b/lib/twiml.ex
@@ -2,23 +2,40 @@ defmodule TwiML do
   import TwiML.Camelize, only: [camelize: 2]
 
   @external_resource "README.md"
-  @moduledoc "README.md"
-             |> File.read!()
-             |> String.split("<!-- MDOC !-->")
-             |> Enum.fetch!(1)
+  @moduledoc """
+  Generate complex TwiML documents for Twilio in an elegant Elixir way.
+
+  > #### Note {: .warning}
+  >
+  > Please refer to the [official TwiML
+  > documentation](https://www.twilio.com/docs/voice/twiml) to verify that the
+  > TwiML verb actually supports content or the given attributes.
+
+  #{"README.md" |> File.read!() |> String.split("<!-- MDOC !-->") |> Enum.fetch!(1)}
+  """
 
   use TwiML.Magic,
     # The nesting and duplication is intentionally as it improves comparing the
     # verbs with the official TwiML at https://www.twilio.com/docs/voice/twiml
     verbs: [
       [:connect, :autopilot, :siprec, :stream, :virtual_agent],
-      [:dial, :client, [:identity, :parameter], :conference, :number, :queue, :sim, :sip],
+      [
+        :dial,
+        :application,
+        :client,
+        [:identity, :parameter],
+        :conference,
+        :number,
+        :queue,
+        :sim,
+        :sip
+      ],
       :enqueue,
       :gather,
       :hangup,
       :leave,
       :pause,
-      [:pay, :prompt],
+      [:pay, :prompt, :parameter],
       :play,
       :record,
       :redirect,
@@ -29,6 +46,31 @@ defmodule TwiML do
       :stream
     ]
 
+  @typedoc """
+  A TwiML document contains one or more TwiML verbs. These verbs can have
+  attributes and can wrap nested TwiML verbs.
+  """
+  @type t :: [{atom(), keyword(), content() | t()}]
+
+  @typedoc """
+  Content which can be used within a TwiML verb. Refer to the `XmlBuilder`
+  documentation for more information.
+  """
+  @type content :: binary() | {:safe, binary()} | {:cdata, binary()} | {:iodata, binary()}
+
+  @doc """
+  Generates a XML document from the provided verbs and arguments. For the
+  supported `opts`, please refer to the documentation of
+  `XmlBuilder.generate/2`.
+
+  ## Examples
+
+      iex> TwiML.say("Hello world")
+      ...> |> TwiML.to_xml(format: :none)
+      ~s(<?xml version="1.0" encoding="UTF-8"?><Response><Say>Hello world</Say></Response>)
+
+  """
+  @doc helper: true
   def to_xml(verbs, opts \\ []) do
     XmlBuilder.document(:Response, verbs)
     |> XmlBuilder.generate(opts)
@@ -49,10 +91,31 @@ defmodule TwiML do
     {verb, attrs, children}
   end
 
+  @doc """
+  Generates a comment.
+
+  ## Examples
+
+      iex> TwiML.comment("Blocked because of insufficient funds")
+      ...> |> TwiML.to_xml(format: :none)
+      ~s(<?xml version="1.0" encoding="UTF-8"?><Response><!-->Blocked because of insufficient funds</!--></Response>)
+
+  """
+  @doc helper: true
   def comment(text) do
     [{"!--", [], text}]
   end
 
+  @doc """
+  Appends a comment to the TwiML.
+
+  ## Examples
+
+      iex> TwiML.reject() |> TwiML.comment("Blocked because of insufficient funds") |> TwiML.to_xml(format: :none)
+      ~s(<?xml version="1.0" encoding="UTF-8"?><Response><Reject/><!-->Blocked because of insufficient funds</!--></Response>)
+
+  """
+  @doc helper: true
   def comment(verbs, text) do
     verbs ++ [comment(text)]
   end

diff --git a/lib/twiml/magic.ex b/lib/twiml/magic.ex
@@ -12,10 +12,30 @@ defmodule TwiML.Magic do
 
   def twiml_verb(verb) do
     quote do
+      twiml = TwiML.Camelize.camelize(Atom.to_string(unquote(verb)))
+
+      @doc """
+      Generates an empty `<#{twiml}>` verb.
+      """
+      @spec unquote(verb)() :: TwiML.t()
       def unquote(verb)() do
         [build_verb(unquote(verb), [], [])]
       end
 
+      @doc """
+      Generates a `<#{twiml}>` verb.
+
+      There are three supported usages:
+
+      - Wraps `arg` in `<#{twiml}>` if it's `t:TwiML.content/0`.
+      - Creates an empty `<#{twiml}>` with attributes for `arg` as a keyword
+        list.
+      - Appends an empty `<#{twiml}>` to `arg` if it's `t:TwiML.t/0`, enabling
+        verb chaining (refer to [Examples](#module-examples)).
+      """
+      @spec unquote(verb)(TwiML.content() | keyword() | TwiML.t()) :: TwiML.t()
+      def unquote(verb)(arg)
+
       def unquote(verb)(content) when is_binary(content) do
         [build_verb(unquote(verb), [], content)]
       end
@@ -40,10 +60,30 @@ defmodule TwiML.Magic do
         end
       end
 
+      @doc """
+      Appends or generates a `<#{twiml}>` verb.
+
+      There are two supported usages:
+
+      - Appends `<#{twiml}>` to `verbs_or_content` if it's `t:TwiML.t/0`,
+        enabling verb chaining (see [Examples](#module-examples)). This verb
+        wraps `content_or_attrs` if it's `t:TwiML.content/0`, or includes
+        attributes if `content_or_attrs` is a keyword list.
+      - Generates `<#{twiml}>` with attributes if `content_or_attrs` is a
+        keyword list.
+      """
+      def unquote(verb)(verbs_or_content, content_or_attrs)
+
+      @spec unquote(verb)(TwiML.t(), keyword() | TwiML.content()) :: TwiML.t()
       def unquote(verb)(verbs, attrs) when is_list(verbs) and is_list(attrs) do
         verbs ++ [build_verb(unquote(verb), attrs, [])]
       end
 
+      def unquote(verb)(verbs, content) when is_binary(content) do
+        verbs ++ [build_verb(unquote(verb), [], content)]
+      end
+
+      @spec unquote(verb)(TwiML.content(), keyword()) :: TwiML.t()
       def unquote(verb)(content, attrs) when is_binary(content) do
         [build_verb(unquote(verb), attrs, content)]
       end
@@ -60,28 +100,60 @@ defmodule TwiML.Magic do
         [build_verb(unquote(verb), attrs, content)]
       end
 
-      def unquote(verb)(verbs, content) when is_binary(content) do
-        verbs ++ [build_verb(unquote(verb), [], content)]
-      end
+      @doc """
+      Appends a `<#{twiml}>` verb with attributes.
 
+      Adds a `<#{twiml}>` verb to `verbs` using `attrs` as attributes,
+      facilitating verb chaining (see [Examples](#module-examples)).
+      """
+      @spec unquote(verb)(TwiML.t(), TwiML.content(), keyword()) :: TwiML.t()
       def unquote(verb)(verbs, content, attrs)
           when is_list(verbs) and is_binary(content) and is_list(attrs) do
         verbs ++ [build_verb(unquote(verb), attrs, content)]
       end
 
-      # How many of the preceding XML elements should be put into this one as
-      # children? By default :all will be put in.
-      def unquote(String.to_atom("into_#{verb}"))(verbs, last_n_elements \\ :all)
+      @doc """
+      Wraps preceding TwiML verbs in a `<#{twiml}>` verb.
+
+      There are three supported usages:
+      - Uses `attrs_or_last_n_elements` as attributes to wrap all preceding verbs
+        in `<#{twiml}>` if it's a keyword list.
+      - Wraps all preceding verbs in `<#{twiml}>` if `attrs_or_last_n_elements` is
+        `:all`.
+      - Encloses the last `attrs_or_last_n_elements` verbs in `<#{twiml}>` if it's a
+        positive integer.
+      """
+      @spec unquote(String.to_atom("into_#{verb}"))(
+              TwiML.t(),
+              keyword() | :all | pos_integer()
+            ) :: TwiML.t()
+      def unquote(String.to_atom("into_#{verb}"))(verbs, attrs_or_last_n_elements \\ :all)
 
-      def unquote(String.to_atom("into_#{verb}"))(verbs, last_n_elements)
-          when is_integer(last_n_elements) or is_atom(last_n_elements) do
-        unquote(String.to_atom("into_#{verb}"))(verbs, last_n_elements, [])
+      def unquote(String.to_atom("into_#{verb}"))(verbs, attrs_or_last_n_elements)
+          when is_integer(attrs_or_last_n_elements) or is_atom(attrs_or_last_n_elements) do
+        unquote(String.to_atom("into_#{verb}"))(verbs, attrs_or_last_n_elements, [])
       end
 
       def unquote(String.to_atom("into_#{verb}"))(verbs, attrs) when is_list(attrs) do
         unquote(String.to_atom("into_#{verb}"))(verbs, :all, attrs)
       end
 
+      @doc """
+      Wraps preceding TwiML verbs in a `<#{twiml}>` verb with attributes.
+
+      There are three supported usages:
+      - Wraps all preceding verbs in `<#{twiml}>` using `attrs` as attributes if
+        `last_n_elements` is `:all`.
+      - Encloses the last `last_n_elements` verbs in `<#{twiml}>` using `attrs`
+        as attribute if it's a positive integer.
+      """
+      @spec unquote(String.to_atom("into_#{verb}"))(
+              TwiML.t(),
+              :all | pos_integer(),
+              keyword()
+            ) :: TwiML.t()
+      def unquote(String.to_atom("into_#{verb}"))(verbs, last_n_elements, attrs)
+
       def unquote(String.to_atom("into_#{verb}"))(verbs, :all, attrs) do
         [build_verb(unquote(verb), attrs, [verbs])]
       end

diff --git a/mix.exs b/mix.exs
@@ -22,15 +22,22 @@ defmodule Twiml.MixProject do
       # Docs
       name: "TwiML",
       source_url: @url,
-      docs: [main: "TwiML", source_ref: "v#{@version}"]
+      docs: [
+        main: "TwiML",
+        source_ref: "v#{@version}",
+        groups_for_docs: [
+          {:Types, &(&1[:kind] == :type)},
+          {:"TwiML Verbs", &(!&1[:helper])}
+        ]
+      ]
     ]
   end
 
   # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
       {:xml_builder, "~> 2.2"},
-      {:ex_doc, "~> 0.24", only: :docs}
+      {:ex_doc, "~> 0.31", only: :docs}
     ]
   end
 

diff --git a/mix.lock b/mix.lock
@@ -1,9 +1,9 @@
 %{
-  "earmark_parser": {:hex, :earmark_parser, "1.4.19", "de0d033d5ff9fc396a24eadc2fcf2afa3d120841eb3f1004d138cbf9273210e8", [:mix], [], "hexpm", "527ab6630b5c75c3a3960b75844c314ec305c76d9899bb30f71cb85952a9dc45"},
-  "ex_doc": {:hex, :ex_doc, "0.27.0", "5600033896bbcf754c8de49262ae305cf7717d964710c25f488f9c659c22a3c3", [:mix], [{:earmark_parser, "~> 1.4.19", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "38c5d707aa317480e8ba7fa5fbfcb8028662135d448679e8ef6206c47d106aa0"},
-  "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.15.2", "dc72dfe17eb240552857465cc00cce390960d9a0c055c4ccd38b70629227e97c", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "fd23ae48d09b32eff49d4ced2b43c9f086d402ee4fd4fcb2d7fad97fa8823e75"},
-  "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
-  "nimble_parsec": {:hex, :nimble_parsec, "1.2.0", "b44d75e2a6542dcb6acf5d71c32c74ca88960421b6874777f79153bbbbd7dccc", [:mix], [], "hexpm", "52b2871a7515a5ac49b00f214e4165a40724cf99798d8e4a65e4fd64ebd002c1"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"},
+  "ex_doc": {:hex, :ex_doc, "0.31.0", "06eb1dfd787445d9cab9a45088405593dd3bb7fe99e097eaa71f37ba80c7a676", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.1", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "5350cafa6b7f77bdd107aa2199fe277acf29d739aba5aee7e865fc680c62a110"},
+  "makeup": {:hex, :makeup, "1.1.1", "fa0bc768698053b2b3869fa8a62616501ff9d11a562f3ce39580d60860c3a55e", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "5dc62fbdd0de44de194898b6710692490be74baa02d9d108bc29f007783b0b48"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
+  "makeup_erlang": {:hex, :makeup_erlang, "0.1.3", "d684f4bac8690e70b06eb52dad65d26de2eefa44cd19d64a8095e1417df7c8fd", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "b78dc853d2e670ff6390b605d807263bf606da3c82be37f9d7f68635bd886fc9"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
   "xml_builder": {:hex, :xml_builder, "2.2.0", "cc5f1eeefcfcde6e90a9b77fb6c490a20bc1b856a7010ce6396f6da9719cbbab", [:mix], [], "hexpm", "9d66d52fb917565d358166a4314078d39ef04d552904de96f8e73f68f64a62c9"},
 }