Misc doc changes

Besides other documentation changes, this commit ensures the generated
HTML doc for HexDocs.pm will become the main reference doc for this
Elixir library which leverage on latest features of ExDoc.

Author: kianmeng

.formatter.exs

@@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

.gitignore

@@ -1,10 +1,33 @@
-/ebin
-/deps
-/doc
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
 erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
 *.ez
+
+# Ignore package tarball (built via "mix hex.build").
+mailman-*.tar
+
+# Temporary files for e.g. tests
+/tmp/
+
+# Misc.
+/ebin
 *.swp
 *.swo
 *.swn
 *.swm
-/_build

CONTRIBUTORS.md

@@ -1,33 +1,34 @@
 # Contributors
 
-Thank you to all of these wonderful individuals who have contributed to Mailman:
+Thank you to all of these wonderful individuals who have contributed to
+Mailman, sorted in alphabetical order:
 
-* Josh Adams (https://github.com/knewter)
+* Anthony Graham (https://github.com/trinode)
+* Arunvel Sriram (https://github.com/arunvelsriram)
+* Benjamin Nørgaard (https://github.com/blacksails)
 * Dan McClain (https://github.com/danmcclain)
-* Holger Amann (https://github.com/hamann)
-* Low Kian Seong (https://github.com/lowks)
-* Stian Håklev (https://github.com/houshuang)
 * Dejan Štrbac (https://github.com/dejanstrbac)
-* Benjamin Nørgaard (https://github.com/blacksails)
-* JustMikey (https://github.com/JustMikey)
-* swerter (https://github.com/swerter)
-* Richard Leland (https://github.com/richleland)
-* Max Neuvians (https://github.com/maxneuvians)
-* Jeff Weiss (https://github.com/jeffweiss)
-* Mickaël Rémond (https://github.com/mremond)
-* Anthony Graham (https://github.com/trinode)
 * Gerry Shaw (https://github.com/gshaw)
-* Martin Maillard (https://github.com/martinmaillard)
+* Holger Amann (https://github.com/hamann)
+* Jeff Weiss (https://github.com/jeffweiss)
+* Josh Adams (https://github.com/knewter)
+* JustMikey (https://github.com/JustMikey)
+* Kamil Ciemniewski (https://github.com/kamilc)
 * Keitaroh Kobayashi (https://github.com/keichan34)
-* Arunvel Sriram (https://github.com/arunvelsriram)
+* Low Kian Seong (https://github.com/lowks)
 * Martin Chabot (https://github.com/martinos)
-* Mike Martinson (https://github.com/mmartinson)
-* Wojciech Stachowski (https://github.com/Antiavanti)
-* Uģis Ozols (https://github.com/ugisozols)
+* Martin Maillard (https://github.com/martinmaillard)
 * Martin Schurig (https://github.com/schurig)
 * Mathieu Rhéaume (https://github.com/ddrmanxbxfr)
+* Max Neuvians (https://github.com/maxneuvians)
+* Mickaël Rémond (https://github.com/mremond)
+* Mike Martinson (https://github.com/mmartinson)
+* Richard Leland (https://github.com/richleland)
 * Sebastian Kosch (https://github.com/skosch)
-* Kamil Ciemniewski (https://github.com/kamilc)
+* Stian Håklev (https://github.com/houshuang)
+* Uģis Ozols (https://github.com/ugisozols)
+* Wojciech Stachowski (https://github.com/Antiavanti)
+* swerter (https://github.com/swerter)
 
 
 (Please let us know if you should be included on this list.)

LICENSE

@@ -1 +1 @@
-LICENSE.txt
+LICENSE.md

LICENSE.txt renamed to LICENSE.md

@@ -1,8 +1,11 @@
 # Mailman 👮
 
-![Elixir CI](https://github.com/mailman-elixir/mailman/workflows/Elixir%20CI/badge.svg)
-[![Docs](https://img.shields.io/badge/api-docs-green.svg?style=flat)](https://hexdocs.pm/mailman)
-[![Hex.pm Version](http://img.shields.io/hexpm/v/mailman.svg?style=flat)](https://hex.pm/packages/mailman)
+[![Elixir CI](https://github.com/mailman-elixir/mailman/actions/workflows/elixir.yml/badge.svg)](https://github.com/mailman-elixir/mailman/actions/workflows/elixir.yml)
+[![Module Version](https://img.shields.io/hexpm/v/mailman.svg)](https://hex.pm/packages/mailman)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/mailman/)
+[![Total Download](https://img.shields.io/hexpm/dt/mailman.svg)](https://hex.pm/packages/mailman)
+[![License](https://img.shields.io/hexpm/l/mailman.svg)](https://github.com/mailman-elixir/mailman/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/mailman-elixir/mailman.svg)](https://github.com/mailman-elixir/mailman/commits/master)
 
 Mailman lets you send email from your Elixir app.
 
@@ -18,8 +21,17 @@ Mailman lets you send email from your Elixir app.
 
 Mailman is a wrapper around the mighty (but rather low-level) [gen_smtp](https://github.com/vagabond/gen_smtp), the popular Erlang SMTP library.
 
+## Which email library should I choose? Mailman vs. Bamboo vs. Swoosh
+The Elixir ecosystem now offers a number of email libraries to choose from.
 
-## Simple example 
+Mailman has been around the longest. As an Elixir wrapper around the battle-tested [gen_smtp](https://github.com/vagabond/gen_smtp) client, it is designed primarily with SMTP power users in mind. If you are interfacing directly with an SMTP relay, Mailman is for you.
+
+If you instead work with a commercial email service like SendGrid or Mailgun, consider libraries like [Bamboo](https://github.com/thoughtbot/bamboo) and [Swoosh](https://github.com/swoosh/swoosh), which come with clients for these services. Note that both of these libraries offer SMTP adapters as well.
+
+
+## Simple example
+
+Emails are sent using the `Mailman.deliver` function. All you need is the email itself and a `%Mailman.Context{}` configuration struct:
 
 ```elixir
 context = %Mailman.Context{
@@ -55,3 +67,10 @@ email = %Mailman.Email{
 
 Mailman.deliver(email, context)
 ```
+
+## Copyright and License
+
+Copyright (c) 2012 Kamil Ciemniewski
+
+Mailman is released under the MIT License. See the [LICENSE.md](./LICENSE.md) file
+for further details.

README.md

@@ -1,16 +1,25 @@
 defmodule Mailman do
+  @moduledoc """
+  Provides functions to send email.
+  """
 
   defprotocol Adapter do
-    @moduledoc "Protocol for implementing different medium of emails delivery"
+    @moduledoc """
+    Protocol for implementing different medium of emails delivery.
+    """
     def deliver(context, email, message)
   end
 
   defprotocol Composer do
-    @moduledoc "Protocol for implementing different template systems for compiling email bodies"
+    @moduledoc """
+    Protocol for implementing different template systems for compiling email bodies.
+    """
     def compile_part(config, mode, email)
   end
 
-  @doc "Delivers given email to all addresses and returns a list of Tasks"
+  @doc """
+  Delivers given email to all addresses and returns a list of Tasks.
+  """
   def deliver(email, context, :send_cc_and_bcc, extra_headers) do
     bcc_list = email.bcc
     cleaned_email = %Mailman.Email{email | bcc: []}
@@ -19,12 +28,12 @@ defmodule Mailman do
 
     to_task = [Adapter.deliver(config, email, message)]
 
-    cc_tasks = email.cc |> Enum.map(fn(address) ->  
+    cc_tasks = email.cc |> Enum.map(fn(address) ->
       cc_envelope = %Mailman.Email{email | to: [address]}
       Adapter.deliver(config, cc_envelope, message)
     end)
 
-    bcc_tasks = bcc_list |> Enum.map(fn(address) ->  
+    bcc_tasks = bcc_list |> Enum.map(fn(address) ->
       bcc_envelope = %Mailman.Email{email | to: [address]}
       bcc_message = %Mailman.Email{email | bcc: [address]}
       message = Mailman.Render.render(bcc_message, context.composer)
@@ -38,7 +47,9 @@ defmodule Mailman do
     deliver(email, context, :send_cc_and_bcc, [])
   end
 
-  @doc "Delivers given email and returns a Task"
+  @doc """
+  Delivers given email and returns a Task.
+  """
   def deliver(email, context, extra_headers) do
     message = Mailman.Render.render(email, context.composer, extra_headers)
     Adapter.deliver(Mailman.Context.get_config(context), email, message)

docs/Overview.md

@@ -1,5 +1,8 @@
 defmodule Mailman.Attachment do
-  @moduledoc "A struct defining an attachable file. It automatically detect the mime type based on file extension."
+  @moduledoc """
+  A struct defining an attachable file. It automatically detect the mime type
+  based on file extension.
+  """
 
   defstruct file_name: "",
             mime_type: "",
@@ -718,14 +721,19 @@ defmodule Mailman.Attachment do
     end
   end
 
-  @doc "Get the attachment struct with disposition 'inline'."
+  @doc """
+  Get the attachment struct with disposition 'inline'.
+  """
   @spec inline(String.t(), String.t(), {String.t(), String.t()}) ::
           {:ok, t} | {:error, String.t()}
   def inline(url_or_file_path, file_name \\ nil, mime_tuple \\ nil) do
     create(url_or_file_path, "inline", file_name, mime_tuple)
   end
 
-  @doc "Get the attachment struct with disposition 'inline'. Throw an error if anything goes wrong."
+  @doc """
+  Get the attachment struct with disposition 'inline'. Throw an error if
+  anything goes wrong.
+  """
   @spec inline(String.t(), String.t(), {String.t(), String.t()}) :: t
   def inline!(url_or_file_path, file_name \\ nil, mime_tuple \\ nil) do
     case inline(url_or_file_path, file_name, mime_tuple) do
@@ -734,12 +742,17 @@ defmodule Mailman.Attachment do
     end
   end
 
-  @doc "Get the attachment struct with disposition 'attachment'."
+  @doc """
+  Get the attachment struct with disposition 'attachment'.
+  """
   def attach(url_or_file_path, file_name \\ nil, mime_tuple \\ nil) do
     create(url_or_file_path, "attachment", file_name, mime_tuple)
   end
 
-  @doc "Get the attachment struct with disposition 'attachment'. Throw an error if anything goes wrong."
+  @doc """
+  Get the attachment struct with disposition 'attachment'. Throw an error if
+  anything goes wrong.
+  """
   def attach!(url_or_file_path, file_name \\ nil, mime_tuple \\ nil) do
     case attach(url_or_file_path, file_name, mime_tuple) do
       {:ok, attachment} -> attachment

docs/Delivery.md renamed to guides/checking_for_successfully_delivery.md

@@ -1,5 +1,7 @@
 defmodule Mailman.Context do
-  @moduledoc "Defines the configuration for both rendering and sending of messages"
+  @moduledoc """
+  Defines the configuration for both rendering and sending of messages.
+  """
 
   defstruct config: nil, composer: %Mailman.EexComposeConfig{}
 

docs/MixConfig.md renamed to guides/configuration_tips.md

@@ -1,5 +1,7 @@
 defmodule Mailman.EexComposer do
-  @moduledoc "Provides functions for rendering from Eex template files"
+  @moduledoc """
+  Provides functions for rendering from Eex template files.
+  """
 
   def compile_part(config, :html, %{html: template, data: data}) do
     if config.html_file do

docs/Email.md renamed to guides/creating_emails.md

@@ -1,7 +1,9 @@
 defmodule Mailman.EexComposeConfig do
-  @moduledoc "Defines the config for the Eex composer"
+  @moduledoc """
+  Defines the config for the EEx composer.
+  """
 
-  defstruct root_path: "", assets_path: "", 
+  defstruct root_path: "", assets_path: "",
             text_file: false, html_file: false,
             text_file_path: "", html_file_path: ""
 end

docs/LocalTestAdapters.md renamed to guides/local_and_test_adapter_config.md

@@ -1,23 +1,25 @@
 defmodule Mailman.Email do
-  @moduledoc "Struct representing an email message"
+  @moduledoc """
+  Struct representing an email message.
+  """
 
   defstruct subject: "",
-    from: "",
-    reply_to: "",
-    to: [],
-    cc: [],
-    bcc: [],
-    attachments: [],
-    data: %{},
-    html: "",
-    text: "",
-    delivery: nil
+            from: "",
+            reply_to: "",
+            to: [],
+            cc: [],
+            bcc: [],
+            attachments: [],
+            data: %{},
+            html: "",
+            text: "",
+            delivery: nil
 
-    def parse(message) do
-      Mailman.Parsing.parse message
-    end
+  def parse(message) do
+    Mailman.Parsing.parse(message)
+  end
 
-    def parse!(message) do
-      Mailman.Parsing.parse! message
-    end
+  def parse!(message) do
+    Mailman.Parsing.parse!(message)
+  end
 end

docs/Rendering.md renamed to guides/rendering_using_eex.md

@@ -1,7 +1,11 @@
 defmodule Mailman.ExternalSmtpAdapter do
-  @moduledoc "Adapter for sending email via external SMTP server"
+  @moduledoc """
+  Adapter for sending email via external SMTP server.
+  """
 
-  @doc "Delivers an email based on specified config"
+  @doc """
+  Delivers an email based on specified config.
+  """
   def deliver(config, email, message) do
     relay_config = [
       relay: config.relay,