From 62310a9cbcbb88a9ec08061d93946bf0f096bbbc Mon Sep 17 00:00:00 2001
From: Andrew Summers <oasummerso@gmail.com>
Date: Mon, 11 Nov 2019 06:29:46 -0600
Subject: [PATCH] Move explanations to module docs. (#373)

---
 lib/dialyxir/warnings/apply.ex                | 28 +++---
 lib/dialyxir/warnings/call.ex                 | 32 +++---
 .../warnings/call_to_missing_function.ex      | 46 ++++-----
 lib/dialyxir/warnings/call_without_opaque.ex  | 48 ++++-----
 .../callback_argument_type_mismatch.ex        | 37 +++----
 .../warnings/callback_info_missing.ex         | 31 +++---
 lib/dialyxir/warnings/callback_missing.ex     | 41 ++++----
 .../callback_spec_argument_type_mismatch.ex   | 38 ++++----
 .../warnings/callback_spec_type_mismatch.ex   | 38 ++++----
 .../warnings/callback_type_mismatch.ex        | 38 ++++----
 lib/dialyxir/warnings/contract_subtype.ex     | 38 ++++----
 lib/dialyxir/warnings/contract_supertype.ex   | 28 +++---
 lib/dialyxir/warnings/contract_with_opaque.ex | 36 +++----
 lib/dialyxir/warnings/exact_equality.ex       | 24 ++---
 lib/dialyxir/warnings/extra_range.ex          | 27 +++---
 .../function_application_no_function.ex       | 26 ++---
 lib/dialyxir/warnings/guard_fail.ex           | 50 +++++-----
 lib/dialyxir/warnings/guard_fail_pattern.ex   | 26 ++---
 lib/dialyxir/warnings/invalid_contract.ex     | 35 ++++---
 lib/dialyxir/warnings/map_update.ex           | 30 +++---
 lib/dialyxir/warnings/negative_guard_fail.ex  | 50 +++++-----
 lib/dialyxir/warnings/no_return.ex            | 60 ++++++------
 lib/dialyxir/warnings/opaque_match.ex         | 51 +++++-----
 lib/dialyxir/warnings/overlapping_contract.ex | 37 +++----
 lib/dialyxir/warnings/pattern_match.ex        | 35 +++----
 .../warnings/pattern_match_covered.ex         | 35 +++----
 lib/dialyxir/warnings/unknown_type.ex         | 32 +++---
 lib/dialyxir/warnings/unmatched_return.ex     | 97 ++++++++++---------
 lib/dialyxir/warnings/unused_function.ex      | 37 +++----
 29 files changed, 594 insertions(+), 537 deletions(-)

diff --git a/lib/dialyxir/warnings/apply.ex b/lib/dialyxir/warnings/apply.ex
index 601ab366..49bd6c51 100644
--- a/lib/dialyxir/warnings/apply.ex
+++ b/lib/dialyxir/warnings/apply.ex
@@ -1,4 +1,18 @@
 defmodule Dialyxir.Warnings.Apply do
+  @moduledoc """
+  The function being invoked exists, and has the correct arity, but
+  will not succeed.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          fun = fn :ok -> :ok end
+          fun.(:error)
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -32,18 +46,6 @@ defmodule Dialyxir.Warnings.Apply do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The function being invoked exists, and has the correct arity, but
-    will not succeed.
-
-    Example:
-
-    defmodule Example do
-      def ok() do
-        fun = fn :ok -> :ok end
-        fun.(:error)
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/call.ex b/lib/dialyxir/warnings/call.ex
index 3006b8e9..d318cbc6 100644
--- a/lib/dialyxir/warnings/call.ex
+++ b/lib/dialyxir/warnings/call.ex
@@ -1,4 +1,20 @@
 defmodule Dialyxir.Warnings.Call do
+  @moduledoc """
+  The function call will not succeed.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          ok(:error)
+        end
+
+        def ok(:ok) do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -47,20 +63,6 @@ defmodule Dialyxir.Warnings.Call do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The function call will not succeed.
-
-    Example:
-
-    defmodule Example do
-      def ok() do
-        ok(:error)
-      end
-
-      def ok(:ok) do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/call_to_missing_function.ex b/lib/dialyxir/warnings/call_to_missing_function.ex
index 765bccda..69b7b9c2 100644
--- a/lib/dialyxir/warnings/call_to_missing_function.ex
+++ b/lib/dialyxir/warnings/call_to_missing_function.ex
@@ -1,4 +1,27 @@
 defmodule Dialyxir.Warnings.CallToMissingFunction do
+  @moduledoc """
+  Function calls a missing or private function. This may be caused by
+  a typo or incorrect arity. This is also a compiler warning.
+
+  ## Example
+
+      defmodule Missing do
+        def missing(:ok) do
+          :ok
+        end
+
+        defp missing() do
+          :ok
+        end
+      end
+
+      defmodule Example do
+        def error() do
+          Missing.missing()
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -19,27 +42,6 @@ defmodule Dialyxir.Warnings.CallToMissingFunction do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Function calls a missing or private function. This may be caused by a typo or
-    incorrect arity. This is also a compiler warning.
-
-    Example:
-
-    defmodule Missing do
-      def missing(:ok) do
-        :ok
-      end
-
-      defp missing() do
-        :ok
-      end
-    end
-
-    defmodule Example do
-      def error() do
-        Missing.missing()
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/call_without_opaque.ex b/lib/dialyxir/warnings/call_without_opaque.ex
index 708d5877..fb5f434a 100644
--- a/lib/dialyxir/warnings/call_without_opaque.ex
+++ b/lib/dialyxir/warnings/call_without_opaque.ex
@@ -1,4 +1,28 @@
 defmodule Dialyxir.Warnings.CallWithoutOpaque do
+  @moduledoc """
+  Function call without opaqueness type mismatch.
+
+  ## Example
+
+      defmodule OpaqueStruct do
+        defstruct [:opaque]
+
+        @opaque t :: %OpaqueStruct{}
+      end
+
+      defmodule Example do
+        @spec error(OpaqueStruct.t()) :: :error
+        def error(struct = %OpaqueStruct{}) do
+          do_error(struct)
+        end
+
+        @spec do_error(OpaqueStruct.t()) :: :error
+        defp do_error(_) do
+          :error
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -50,28 +74,6 @@ defmodule Dialyxir.Warnings.CallWithoutOpaque do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Function call without opaqueness type mismatch.
-
-    Example:
-
-    defmodule OpaqueStruct do
-      defstruct [:opaque]
-
-      @opaque t :: %OpaqueStruct{}
-    end
-
-    defmodule Example do
-      @spec error(OpaqueStruct.t()) :: :error
-      def error(struct = %OpaqueStruct{}) do
-        do_error(struct)
-      end
-
-      @spec do_error(OpaqueStruct.t()) :: :error
-      defp do_error(_) do
-        :error
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/callback_argument_type_mismatch.ex b/lib/dialyxir/warnings/callback_argument_type_mismatch.ex
index 6b7fcd78..2fb4c592 100644
--- a/lib/dialyxir/warnings/callback_argument_type_mismatch.ex
+++ b/lib/dialyxir/warnings/callback_argument_type_mismatch.ex
@@ -1,4 +1,22 @@
 defmodule Dialyxir.Warnings.CallbackArgumentTypeMismatch do
+  @moduledoc """
+  Type of argument does not match the callback's expected type.
+
+  ## Example
+
+      defmodule ExampleBehaviour do
+        @callback ok(:ok) :: :ok
+      end
+
+      defmodule Example do
+
+        @behaviour ExampleBehaviour
+
+        def ok(:error) do
+          :ok
+        end
+    end
+  """
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -35,23 +53,6 @@ defmodule Dialyxir.Warnings.CallbackArgumentTypeMismatch do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Type of argument does not match the callback's expected type.
-
-    Example:
-
-    defmodule ExampleBehaviour do
-      @callback ok(:ok) :: :ok
-    end
-
-    defmodule Example do
-
-      @behaviour ExampleBehaviour
-
-      def ok(:error) do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/callback_info_missing.ex b/lib/dialyxir/warnings/callback_info_missing.ex
index 25488198..c09ca904 100644
--- a/lib/dialyxir/warnings/callback_info_missing.ex
+++ b/lib/dialyxir/warnings/callback_info_missing.ex
@@ -1,4 +1,19 @@
 defmodule Dialyxir.Warnings.CallbackInfoMissing do
+  @moduledoc """
+  The module is using a behaviour that does not exist or is not a
+  behaviour. This is also a compiler warning.
+
+  ## Example
+
+      defmodule Example do
+        @behaviour BehaviourThatDoesNotExist
+
+        def ok() do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -20,20 +35,6 @@ defmodule Dialyxir.Warnings.CallbackInfoMissing do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The module is using a behaviour that does not exist or is not a
-    behaviour. This is also a compiler warning.
-
-    Example:
-
-    defmodule Example do
-
-      @behaviour BehaviourThatDoesNotExist
-
-      def ok() do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/callback_missing.ex b/lib/dialyxir/warnings/callback_missing.ex
index d1cbe1ca..322e137f 100644
--- a/lib/dialyxir/warnings/callback_missing.ex
+++ b/lib/dialyxir/warnings/callback_missing.ex
@@ -1,4 +1,24 @@
 defmodule Dialyxir.Warnings.CallbackMissing do
+  @moduledoc """
+  Module implements a behaviour, but does not have all of its
+  callbacks. This is also a compiler warning.
+
+  ## Example
+
+      defmodule ExampleBehaviour do
+        @callback ok() :: :ok
+        @callback missing() :: :ok
+      end
+
+      defmodule Example do
+        @behaviour ExampleBehaviour
+
+        def ok() do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -20,25 +40,6 @@ defmodule Dialyxir.Warnings.CallbackMissing do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Module implements a behaviour, but does not have all of its
-    callbacks. This is also a compiler warning.
-
-    Example:
-
-    defmodule ExampleBehaviour do
-      @callback ok() :: :ok
-      @callback missing() :: :ok
-    end
-
-    defmodule Example do
-
-      @behaviour ExampleBehaviour
-
-      def ok() do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/callback_spec_argument_type_mismatch.ex b/lib/dialyxir/warnings/callback_spec_argument_type_mismatch.ex
index 36d05298..bf124f16 100644
--- a/lib/dialyxir/warnings/callback_spec_argument_type_mismatch.ex
+++ b/lib/dialyxir/warnings/callback_spec_argument_type_mismatch.ex
@@ -1,4 +1,23 @@
 defmodule Dialyxir.Warnings.CallbackSpecArgumentTypeMismatch do
+  @moduledoc """
+  Spec type of argument does not match the callback's expected type.
+
+  ## Example
+
+      defmodule ExampleBehaviour do
+        @callback ok(:ok) :: :ok
+      end
+
+      defmodule Example do
+        @behaviour ExampleBehaviour
+
+        @spec ok(:error) :: :ok
+        def ok(:ok) do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -35,23 +54,6 @@ defmodule Dialyxir.Warnings.CallbackSpecArgumentTypeMismatch do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Spec type of argument does not match the callback's expected type.
-
-    Example:
-
-    defmodule ExampleBehaviour do
-      @callback ok(:ok) :: :ok
-    end
-
-    defmodule Example do
-      @behaviour ExampleBehaviour
-
-      @spec ok(:error) :: :ok
-      def ok(:ok) do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/callback_spec_type_mismatch.ex b/lib/dialyxir/warnings/callback_spec_type_mismatch.ex
index 2526c8fc..c9eac9f6 100644
--- a/lib/dialyxir/warnings/callback_spec_type_mismatch.ex
+++ b/lib/dialyxir/warnings/callback_spec_type_mismatch.ex
@@ -1,4 +1,24 @@
 defmodule Dialyxir.Warnings.CallbackSpecTypeMismatch do
+  @moduledoc """
+  The return type in the @spec does not match the
+  expected return type of the behaviour.
+
+  ## Example
+
+      defmodule ExampleBehaviour do
+        @callback ok(:ok) :: :ok
+      end
+
+      defmodule Example do
+        @behaviour ExampleBehaviour
+
+        @spec ok(:ok) :: :error
+        def ok(:ok) do
+          :error
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -33,22 +53,6 @@ defmodule Dialyxir.Warnings.CallbackSpecTypeMismatch do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The return type in the @spec does not match the
-    expected return type of the behaviour.
-
-    defmodule ExampleBehaviour do
-      @callback ok(:ok) :: :ok
-    end
-
-    defmodule Example do
-      @behaviour ExampleBehaviour
-
-      @spec ok(:ok) :: :error
-      def ok(:ok) do
-        :error
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/callback_type_mismatch.ex b/lib/dialyxir/warnings/callback_type_mismatch.ex
index 96ca88f8..34ff6b7e 100644
--- a/lib/dialyxir/warnings/callback_type_mismatch.ex
+++ b/lib/dialyxir/warnings/callback_type_mismatch.ex
@@ -1,4 +1,23 @@
 defmodule Dialyxir.Warnings.CallbackTypeMismatch do
+  @moduledoc """
+  The success type of the function does not match the callback type in
+  the behaviour.
+
+  ## Example
+
+      defmodule ExampleBehaviour do
+        @callback ok() :: :ok
+      end
+
+      defmodule Example do
+        @behaviour ExampleBehaviour
+
+        def ok() do
+          :error
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -32,23 +51,6 @@ defmodule Dialyxir.Warnings.CallbackTypeMismatch do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The success type of the function does not match the callback type
-    in the behaviour.
-
-    Example:
-
-    defmodule ExampleBehaviour do
-      @callback ok() :: :ok
-    end
-
-    defmodule Example do
-      @behaviour ExampleBehaviour
-
-      def ok() do
-        :error
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/contract_subtype.ex b/lib/dialyxir/warnings/contract_subtype.ex
index 2fd46d11..30f4d660 100644
--- a/lib/dialyxir/warnings/contract_subtype.ex
+++ b/lib/dialyxir/warnings/contract_subtype.ex
@@ -1,4 +1,23 @@
 defmodule Dialyxir.Warnings.ContractSubtype do
+  # TODO: could not create warning with this example (and --overspecs)
+  @moduledoc """
+  The type in the @spec does not completely cover the types returned
+  by function.
+
+  ## Example
+
+      defmodule Example do
+        @spec ok(:ok | :error) :: :ok
+        def ok(:ok) do
+          :ok
+        end
+
+        def ok(:error) do
+          :error
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -35,23 +54,6 @@ defmodule Dialyxir.Warnings.ContractSubtype do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    # TODO: could not create warning with this example (and --overspecs)
-    """
-    The type in the @spec does not completely cover the types returned
-    by function.
-
-    Example:
-
-    defmodule Example do
-      @spec ok(:ok | :error) :: :ok
-      def ok(:ok) do
-        :ok
-      end
-
-      def ok(:error) do
-        :error
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/contract_supertype.ex b/lib/dialyxir/warnings/contract_supertype.ex
index 50db9256..ff711bc2 100644
--- a/lib/dialyxir/warnings/contract_supertype.ex
+++ b/lib/dialyxir/warnings/contract_supertype.ex
@@ -1,4 +1,18 @@
 defmodule Dialyxir.Warnings.ContractSupertype do
+  @moduledoc """
+  The @spec, while not incorrect, is more general than the type
+  returned by the function.
+
+  ## Example
+
+      defmodule Example do
+        @spec ok() :: any
+        def ok() do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -35,18 +49,6 @@ defmodule Dialyxir.Warnings.ContractSupertype do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The @spec, while not incorrect, is more general than the type
-    returned by the function.
-
-    Example:
-
-    defmodule Example do
-      @spec ok() :: any
-      def ok() do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/contract_with_opaque.ex b/lib/dialyxir/warnings/contract_with_opaque.ex
index 1ac013be..a517b996 100644
--- a/lib/dialyxir/warnings/contract_with_opaque.ex
+++ b/lib/dialyxir/warnings/contract_with_opaque.ex
@@ -1,4 +1,22 @@
 defmodule Dialyxir.Warnings.ContractWithOpaque do
+  @moduledoc """
+  The @spec says the function is returning an opaque type, but it is
+  returning a different type.
+
+  ## Example
+
+      defmodule Types do
+        @opaque type :: :ok
+      end
+
+      defmodule Example do
+        @spec ok() :: Types.type()
+        def ok() do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -30,22 +48,6 @@ defmodule Dialyxir.Warnings.ContractWithOpaque do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The @spec says the function is returning an opaque type, but it is
-    returning a different type.
-
-    Example:
-
-    defmodule Types do
-      @opaque type :: :ok
-    end
-
-    defmodule Example do
-      @spec ok() :: Types.type()
-      def ok() do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/exact_equality.ex b/lib/dialyxir/warnings/exact_equality.ex
index 89182e4d..6b6331ee 100644
--- a/lib/dialyxir/warnings/exact_equality.ex
+++ b/lib/dialyxir/warnings/exact_equality.ex
@@ -1,4 +1,16 @@
 defmodule Dialyxir.Warnings.ExactEquality do
+  @moduledoc """
+  The expression can never evaluate to true.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          :ok == :error
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -21,16 +33,6 @@ defmodule Dialyxir.Warnings.ExactEquality do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The expression can never evaluate to true.
-
-    Example:
-
-    defmodule Example do
-      def ok() do
-        :ok == :error
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/extra_range.ex b/lib/dialyxir/warnings/extra_range.ex
index 2b37b55b..6764b21a 100644
--- a/lib/dialyxir/warnings/extra_range.ex
+++ b/lib/dialyxir/warnings/extra_range.ex
@@ -1,4 +1,18 @@
 defmodule Dialyxir.Warnings.ExtraRange do
+  @moduledoc """
+  The @spec says the function returns more types than the function
+  actually returns.
+
+  ## Example
+
+      defmodule Example do
+        @spec ok() :: :ok | :error
+        def ok() do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -35,17 +49,6 @@ defmodule Dialyxir.Warnings.ExtraRange do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The @spec says the function returns more types than the function actually returns.
-
-    Example:
-
-    defmodule Example do
-      @spec ok() :: :ok | :error
-      def ok() do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/function_application_no_function.ex b/lib/dialyxir/warnings/function_application_no_function.ex
index 26853641..42582216 100644
--- a/lib/dialyxir/warnings/function_application_no_function.ex
+++ b/lib/dialyxir/warnings/function_application_no_function.ex
@@ -1,4 +1,17 @@
 defmodule Dialyxir.Warnings.FunctionApplicationNoFunction do
+  @moduledoc """
+  The function being invoked exists, but has an arity mismatch.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          fun = fn _ -> :ok end
+          fun.()
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -25,17 +38,6 @@ defmodule Dialyxir.Warnings.FunctionApplicationNoFunction do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The function being invoked exists, but has an arity mismatch.
-
-    Example:
-
-    defmodule Example do
-      def ok() do
-        fun = fn _ -> :ok end
-        fun.()
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/guard_fail.ex b/lib/dialyxir/warnings/guard_fail.ex
index 2a303ec1..1860acc6 100644
--- a/lib/dialyxir/warnings/guard_fail.ex
+++ b/lib/dialyxir/warnings/guard_fail.ex
@@ -1,4 +1,29 @@
 defmodule Dialyxir.Warnings.GuardFail do
+  @moduledoc """
+  The function guard either presents an impossible guard or the only
+  calls will never succeed against the guards.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          ok(0)
+        end
+
+        defp ok(n) when n > 1 do
+          :ok
+        end
+      end
+
+    or
+
+      defmodule Example do
+        def ok() when 0 > 1 do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -46,29 +71,6 @@ defmodule Dialyxir.Warnings.GuardFail do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The function guard either presents an impossible guard or the only
-    calls will never succeed against the guards.
-
-    Example:
-
-    defmodule Example do
-      def ok() do
-        ok(0)
-      end
-
-      defp ok(n) when n > 1 do
-        :ok
-      end
-    end
-
-    or
-
-    defmodule Example do
-      def ok() when 0 > 1 do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/guard_fail_pattern.ex b/lib/dialyxir/warnings/guard_fail_pattern.ex
index 4657d1a8..ef9bccb5 100644
--- a/lib/dialyxir/warnings/guard_fail_pattern.ex
+++ b/lib/dialyxir/warnings/guard_fail_pattern.ex
@@ -1,4 +1,17 @@
 defmodule Dialyxir.Warnings.GuardFailPattern do
+  @moduledoc """
+  The clause guard describes a condition of literals that fails the pattern
+  given in the function head.
+
+  ## Example
+
+      defmodule Example do
+        def ok(n = 0) when not n < 1 do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -24,17 +37,6 @@ defmodule Dialyxir.Warnings.GuardFailPattern do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The clause guard describes a condition of literals that fails the pattern
-    given in the function head.
-
-    Example:
-
-    defmodule Example do
-      def ok(n = 0) when not n < 1 do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/invalid_contract.ex b/lib/dialyxir/warnings/invalid_contract.ex
index 69702de1..c16e68c9 100644
--- a/lib/dialyxir/warnings/invalid_contract.ex
+++ b/lib/dialyxir/warnings/invalid_contract.ex
@@ -1,4 +1,22 @@
 defmodule Dialyxir.Warnings.InvalidContract do
+  @moduledoc """
+  The @spec for the function does not match the success typing of the
+  function.
+
+  ## Example
+
+      defmodule Example do
+        @spec process(:error) :: :ok
+        def process(:ok) do
+          :ok
+        end
+      end
+
+  The @spec in this case claims that the function accepts a parameter
+  :error but the function head only accepts :ok, resulting in the
+  mismatch.
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -31,21 +49,6 @@ defmodule Dialyxir.Warnings.InvalidContract do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The @spec for the function does not match the success typing of
-    the function.
-
-    Example:
-
-    defmodule Example do
-      @spec process(:error) :: :ok
-      def process(:ok) do
-        :ok
-      end
-    end
-
-    The @spec in this case claims that the function accepts a parameter :error
-    but the function head only accepts :ok, resulting in the mismatch.
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/map_update.ex b/lib/dialyxir/warnings/map_update.ex
index ea0af263..5b52af8e 100644
--- a/lib/dialyxir/warnings/map_update.ex
+++ b/lib/dialyxir/warnings/map_update.ex
@@ -1,4 +1,19 @@
 defmodule Dialyxir.Warnings.MapUpdate do
+  @moduledoc """
+  Elixir can only use the map update syntax to update a key that is in
+  the map.
+
+  ## Example
+
+      defmodule Example do
+        @spec error() :: map
+        def error() do
+          map = %{exists: :exists}
+          %{map | does_not_exist: :fail}
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -32,19 +47,6 @@ defmodule Dialyxir.Warnings.MapUpdate do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Elixir can only use the map update syntax to update a key that is in the
-    map.
-
-    Example:
-
-    defmodule Example do
-      @spec error() :: map
-      def error() do
-        map = %{exists: :exists}
-        %{map | does_not_exist: :fail}
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/negative_guard_fail.ex b/lib/dialyxir/warnings/negative_guard_fail.ex
index 5d242f93..7ad51d01 100644
--- a/lib/dialyxir/warnings/negative_guard_fail.ex
+++ b/lib/dialyxir/warnings/negative_guard_fail.ex
@@ -1,4 +1,29 @@
 defmodule Dialyxir.Warnings.NegativeGuardFail do
+  @moduledoc """
+  The function guard either presents an impossible guard or the only
+  calls will never succeed against the guards.
+
+  ## Example
+
+      defmodule Example do
+        def ok(ok = "ok") when not is_bitstring(ok) do
+          :ok
+        end
+      end
+
+    or
+
+      defmodule Example do
+        def ok() do
+          ok(:ok)
+        end
+
+        defp ok(ok) when not is_atom(ok) do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -38,29 +63,6 @@ defmodule Dialyxir.Warnings.NegativeGuardFail do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The function guard either presents an impossible guard or the only
-    calls will never succeed against the guards.
-
-    Example:
-
-    defmodule Example do
-      def ok(ok = "ok") when not is_bitstring(ok) do
-        :ok
-      end
-    end
-
-    or
-
-    defmodule Example do
-      def ok() do
-        ok(:ok)
-      end
-
-      defp ok(ok) when not is_atom(ok) do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/no_return.ex b/lib/dialyxir/warnings/no_return.ex
index 51d74137..966e6ac3 100644
--- a/lib/dialyxir/warnings/no_return.ex
+++ b/lib/dialyxir/warnings/no_return.ex
@@ -1,4 +1,35 @@
 defmodule Dialyxir.Warnings.NoReturn do
+  @moduledoc """
+  The function has no return. This is usually due to an issue later on
+  in the call stack causing it to not be recognized as returning for
+  some reason. It is often helpful to cross reference the complete
+  list of warnings with the call stack in the function and fix the
+  deepest part of the call stack, which will usually fix many of the
+  other no_return errors.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          Enum.each([1, 2, 3], fn _ -> raise "error" end)
+        end
+      end
+
+    or
+
+      defmodule Example do
+        def ok() do
+          raise "error"
+
+          :ok
+        end
+
+        def ok(:ok) do
+          ok()
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -42,33 +73,6 @@ defmodule Dialyxir.Warnings.NoReturn do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The function has no return. This is usually due to an issue later
-    on in the call stack causing it to not be recognized as returning
-    for some reason. It is often helpful to cross reference the
-    complete list of warnings with the call stack in the function and
-    fix the deepest part of the call stack, which will usually fix
-    many of the other no_return errors.
-
-    defmodule Example do
-      def ok() do
-        Enum.each([1, 2, 3], fn _ -> raise "error" end)
-      end
-    end
-
-    or
-
-    defmodule Example do
-      def ok() do
-        raise "error"
-
-        :ok
-      end
-
-      def ok(:ok) do
-        ok()
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/opaque_match.ex b/lib/dialyxir/warnings/opaque_match.ex
index 3594dc4b..95659bed 100644
--- a/lib/dialyxir/warnings/opaque_match.ex
+++ b/lib/dialyxir/warnings/opaque_match.ex
@@ -1,4 +1,30 @@
 defmodule Dialyxir.Warnings.OpaqueMatch do
+  @moduledoc """
+  Attempted to pattern match against the internal structure of an
+  opaque term.
+
+  ## Example
+
+      defmodule OpaqueStruct do
+        defstruct [:opaque]
+
+        @opaque t :: %__MODULE__{}
+
+        @spec opaque() :: t
+        def opaque() do
+          %__MODULE__{}
+        end
+      end
+
+      defmodule Example do
+        @spec error() :: :error
+        def error() do
+          %{opaque: _} = OpaqueStruct.opaque()
+          :error
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -45,29 +71,6 @@ defmodule Dialyxir.Warnings.OpaqueMatch do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Attempted to pattern match against the internal structure of an opaque term.
-
-    Example:
-
-    defmodule OpaqueStruct do
-      defstruct [:opaque]
-
-      @opaque t :: %__MODULE__{}
-
-      @spec opaque() :: t
-      def opaque() do
-        %__MODULE__{}
-      end
-    end
-
-    defmodule Example do
-      @spec error() :: :error
-      def error() do
-        %{opaque: _} = OpaqueStruct.opaque()
-        :error
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/overlapping_contract.ex b/lib/dialyxir/warnings/overlapping_contract.ex
index 252766d5..e7642b25 100644
--- a/lib/dialyxir/warnings/overlapping_contract.ex
+++ b/lib/dialyxir/warnings/overlapping_contract.ex
@@ -1,4 +1,22 @@
 defmodule Dialyxir.Warnings.OverlappingContract do
+  @moduledoc """
+  The function has an additional @spec that is already covered more
+  generally by a higher @spec.
+
+  ## Example
+
+      defmodule Example do
+        @spec ok(atom) :: :ok
+        def ok(:ok) do
+          :ok
+        end
+
+        @spec ok(:error) :: :ok
+        def ok(:error) do
+          :ok
+        end
+      end
+  """
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -14,24 +32,7 @@ defmodule Dialyxir.Warnings.OverlappingContract do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The function has an additional @spec that is already covered more
-    generally by a higher @spec.
-
-    Example:
-
-    defmodule Example do
-      @spec ok(atom) :: :ok
-      def ok(:ok) do
-        :ok
-      end
-
-      @spec ok(:error) :: :ok
-      def ok(:error) do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 
   @impl Dialyxir.Warning
diff --git a/lib/dialyxir/warnings/pattern_match.ex b/lib/dialyxir/warnings/pattern_match.ex
index e024b598..c1708536 100644
--- a/lib/dialyxir/warnings/pattern_match.ex
+++ b/lib/dialyxir/warnings/pattern_match.ex
@@ -1,4 +1,21 @@
 defmodule Dialyxir.Warnings.PatternMatch do
+  @moduledoc """
+  The pattern matching is never given a value that satisfies all of
+  its clauses.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          unmatched(:ok)
+        end
+
+        defp unmatched(:ok), do: :ok
+
+        defp unmatched(:error), do: :error
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -32,22 +49,6 @@ defmodule Dialyxir.Warnings.PatternMatch do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The pattern matching is never given a value that satisfies all of
-    its clauses.
-
-    Example:
-
-    defmodule Example do
-
-      def ok() do
-        unmatched(:ok)
-      end
-
-      defp unmatched(:ok), do: :ok
-
-      defp unmatched(:error), do: :error
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/pattern_match_covered.ex b/lib/dialyxir/warnings/pattern_match_covered.ex
index f0675318..231802bc 100644
--- a/lib/dialyxir/warnings/pattern_match_covered.ex
+++ b/lib/dialyxir/warnings/pattern_match_covered.ex
@@ -1,4 +1,21 @@
 defmodule Dialyxir.Warnings.PatternMatchCovered do
+  @moduledoc """
+  The pattern match has a later clause that will never be executed,
+  because a more general clause is higher in the matching order.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          unmatched(:error)
+        end
+
+        defp unmatched(_), do: :ok
+
+        defp unmatched(:error), do: :error
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -30,22 +47,6 @@ defmodule Dialyxir.Warnings.PatternMatchCovered do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The pattern match has a later clause that will never be executed,
-    because a more general clause is higher in the matching order.
-
-    Example:
-
-    defmodule Example do
-
-      def ok() do
-        unmatched(:error)
-      end
-
-      defp unmatched(_), do: :ok
-
-      defp unmatched(:error), do: :error
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/unknown_type.ex b/lib/dialyxir/warnings/unknown_type.ex
index 376aadaf..f851a01c 100644
--- a/lib/dialyxir/warnings/unknown_type.ex
+++ b/lib/dialyxir/warnings/unknown_type.ex
@@ -1,4 +1,20 @@
 defmodule Dialyxir.Warnings.UnknownType do
+  @moduledoc """
+  Spec references a missing @type.
+
+  ## Example
+
+      defmodule Missing do
+      end
+
+      defmodule Example do
+        @spec ok(Missing.t()) :: :ok
+        def ok(_) do
+          :ok
+        end
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -22,20 +38,6 @@ defmodule Dialyxir.Warnings.UnknownType do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Spec references a missing @type.
-
-    Example:
-
-    defmodule Missing do
-    end
-
-    defmodule Example do
-      @spec ok(Missing.t()) :: :ok
-      def ok(_) do
-        :ok
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/unmatched_return.ex b/lib/dialyxir/warnings/unmatched_return.ex
index 43921a63..f7d08f4d 100644
--- a/lib/dialyxir/warnings/unmatched_return.ex
+++ b/lib/dialyxir/warnings/unmatched_return.ex
@@ -1,4 +1,52 @@
 defmodule Dialyxir.Warnings.UnmatchedReturn do
+  @moduledoc """
+  The invoked expression returns a union of types and the call does
+  not match on its return types using e.g. a case or wildcard.
+
+  ## Example
+
+      defmodule Example do
+        require Integer
+
+        def ok() do
+          n = :rand.uniform(100)
+
+          multiple_returns(n)
+
+          :ok
+        end
+
+        defp multiple_returns(n) do
+          if Integer.is_even(n) do
+            :ok
+          else
+            {:error, "error"}
+          end
+        end
+      end
+
+    This would NOT result in a warning:
+
+      defmodule Example do
+        require Integer
+
+        def ok() do
+          n = :rand.uniform(100)
+
+          multiple_returns(n)
+
+          :ok
+        end
+
+        defp multiple_returns(n) do
+          if Integer.is_even(n) do
+            :ok
+          else
+            :error
+          end
+        end
+      end
+  """
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -28,53 +76,6 @@ defmodule Dialyxir.Warnings.UnmatchedReturn do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    The invoked expression returns a union of types and the call does
-    not match on its return types using e.g. a case or wildcard.
-
-    Example:
-
-    defmodule Example do
-      require Integer
-
-      def ok() do
-        n = :rand.uniform(100)
-
-        multiple_returns(n)
-
-        :ok
-      end
-
-      defp multiple_returns(n) do
-        if Integer.is_even(n) do
-          :ok
-        else
-          {:error, "error"}
-        end
-      end
-    end
-
-    This would NOT result in a warning:
-
-    defmodule Example do
-      require Integer
-
-      def ok() do
-        n = :rand.uniform(100)
-
-        multiple_returns(n)
-
-        :ok
-      end
-
-      defp multiple_returns(n) do
-        if Integer.is_even(n) do
-          :ok
-        else
-          :error
-        end
-      end
-    end
-    """
+    @moduledoc
   end
 end
diff --git a/lib/dialyxir/warnings/unused_function.ex b/lib/dialyxir/warnings/unused_function.ex
index d4bd70d1..7a6d14cb 100644
--- a/lib/dialyxir/warnings/unused_function.ex
+++ b/lib/dialyxir/warnings/unused_function.ex
@@ -1,4 +1,22 @@
 defmodule Dialyxir.Warnings.UnusedFunction do
+  @moduledoc """
+  Due to issues higher in the function or call stack, while the
+  function is recognized as used by the compiler, it will never be
+  recognized as having been called until the other error is resolved.
+
+  ## Example
+
+      defmodule Example do
+        def ok() do
+          raise "error"
+
+          unused()
+        end
+
+        defp unused(), do: :ok
+      end
+  """
+
   @behaviour Dialyxir.Warning
 
   @impl Dialyxir.Warning
@@ -18,23 +36,6 @@ defmodule Dialyxir.Warnings.UnusedFunction do
   @impl Dialyxir.Warning
   @spec explain() :: String.t()
   def explain() do
-    """
-    Due to issues higher in the function or call stack, while the
-    function is recognized as used by the compiler, it will never be
-    recognized as having been called until the other error is
-    resolved.
-
-    Example:
-
-    defmodule Example do
-      def ok() do
-        raise "error"
-
-        unused()
-      end
-
-      defp unused(), do: :ok
-    end
-    """
+    @moduledoc
   end
 end