Make documentation easier to find in ExDoc

Author: josevalim

lib/ex_doc.ex

@@ -1,32 +1,6 @@
 defmodule ExDoc do
   @moduledoc """
-  Main entry point for generating docs.
-  """
-  @ex_doc_version Mix.Project.config()[:version]
-
-  @doc """
-  Returns the ExDoc version (used in templates).
-  """
-  @spec version :: String.t()
-  def version, do: @ex_doc_version
-
-  @doc """
-  Emits a warning.
-  """
-  def warn(message, stacktrace_info) do
-    :persistent_term.put({__MODULE__, :warned?}, true)
-    IO.warn(message, stacktrace_info)
-  end
-
-  defp unset_warned() do
-    warned? = :persistent_term.get({__MODULE__, :warned?}, false)
-    :persistent_term.erase({__MODULE__, :warned?})
-    warned?
-  end
-
-  @doc ~S"""
-  Generates documentation for the given `project`, `vsn` (version),
-  `source_beams` directories, and `options`.
+  ExDoc is a tool to generate documentation for Erlang and Elixir projects.
 
   By default it generates HTML, Markdown, and EPUB documents.
 
@@ -512,6 +486,35 @@ defmodule ExDoc do
       all documented versions and their URLs. ExDoc will automatically match
       the version of the package with the one in the array to mark as current.
   """
+  @ex_doc_version Mix.Project.config()[:version]
+
+  @doc """
+  Returns the ExDoc version (used in templates).
+  """
+  @spec version :: String.t()
+  def version, do: @ex_doc_version
+
+  @doc """
+  Emits a warning.
+  """
+  def warn(message, stacktrace_info) do
+    :persistent_term.put({__MODULE__, :warned?}, true)
+    IO.warn(message, stacktrace_info)
+  end
+
+  defp unset_warned() do
+    warned? = :persistent_term.get({__MODULE__, :warned?}, false)
+    :persistent_term.erase({__MODULE__, :warned?})
+    warned?
+  end
+
+  @doc ~S"""
+  Generates documentation for the given `project`, `vsn` (version),
+  `source_beams` directories, and `options`.
+
+  This is the entrypoint called `mix docs` and other tools. See
+  the moduledoc (`ExDoc`) for more information.
+  """
   @spec generate(String.t(), String.t(), [Path.t()], Keyword.t()) ::
           [%{entrypoint: String.t(), warned?: boolean(), formatter: module()}]
   def generate(project, version, source_beams, options)

lib/ex_doc/cli.ex

@@ -228,7 +228,7 @@ defmodule ExDoc.CLI do
     The file must either have ".exs" or ".config" extension.
 
     The file with the ".exs" extension must be an Elixir script that returns
-    a keyword list with the same options declares in `ExDoc.generate/4`.
+    a keyword list with the same options specified in `ExDoc`.
     Here is an example:
 
         [

lib/mix/tasks/docs.ex

@@ -62,7 +62,7 @@ defmodule Mix.Tasks.Docs do
   be set. The following options should be put under the `:docs` key
   in your project's main configuration. The `:docs` options should
   be a keyword list or a function returning a keyword list that will
-  be lazily executed. See all supported options in `ExDoc.generate/4`.
+  be lazily executed. See all supported options in `ExDoc`.
 
   ## Umbrella project