Move explanations to module docs. (#373)

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

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

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

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

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

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

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

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