Add more code comments to modules and TODOs

lib/ex_doc/autolink.ex

@@ -1,4 +1,5 @@
 defmodule ExDoc.Autolink do
+  # Encapsulates all functionality related to autolinking.
   @moduledoc false
 
   # * `:apps` - the apps that the docs are being generated for. When linking modules they are

lib/ex_doc/doc_ast.ex

@@ -1,4 +1,6 @@
 defmodule ExDoc.DocAST do
+  # General helpers for dealing with the documentation AST
+  # (which is the Markdown -> HTML AST).
   @moduledoc false
 
   @type t :: term()

lib/ex_doc/formatter/html/templates.ex

@@ -163,7 +163,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
     [sections: sections]
   end
 
-  # TODO: split into sections in Formatter.HTML instead.
+  # TODO: split into sections in Formatter.HTML instead (possibly via DocAST)
   @h2_regex ~r/<h2.*?>(.*?)<\/h2>/m
   defp extract_headers(content) do
     @h2_regex
@@ -193,8 +193,9 @@ defmodule ExDoc.Formatter.HTML.Templates do
   defp sidebar_type(:livemd), do: "extras"
   defp sidebar_type(:extra), do: "extras"
 
-  # TODO: Move link_headings and friends to html.ex or even to autolinking code,
-  # so content is built with it upfront instead of added at the template level.
+  # TODO: Move link_headings and friends to html.ex (possibly via DocAST)
+  # or even to autolinking code, so content is built with it upfront instead
+  # of added at the template level.
 
   @doc """
   Add link headings for the given `content`.

lib/ex_doc/group_matcher.ex

@@ -1,4 +1,6 @@
 defmodule ExDoc.GroupMatcher do
+  # General helpers for dealing with grouping functionality.
+  # Extracted for organization and testability.
   @moduledoc false
 
   @type pattern :: Regex.t() | module() | String.t()

lib/ex_doc/language/source.ex

@@ -1,4 +1,5 @@
 defmodule ExDoc.Language.Source do
+  # Shared helpers used by both Erlang and Elixir.
   @moduledoc false
 
   def anno_line(line) when is_integer(line), do: abs(line)

lib/ex_doc/refs.ex

@@ -1,13 +1,12 @@
 defmodule ExDoc.Refs do
-  @moduledoc false
-
   # A read-through cache of documentation references.
   #
   # A given ref is always associated with a module. If we don't have a ref
   # in the cache we fetch the module's docs chunk and fill in the cache.
   #
   # If the module does not have the docs chunk, we fetch it's functions,
   # callbacks and types from other sources.
+  @moduledoc false
 
   @typep entry() :: {ref(), visibility()}
 

lib/ex_doc/utils.ex

@@ -1,4 +1,7 @@
 defmodule ExDoc.Utils do
+  # General helpers used throughout ExDoc or extracted for testing.
+  # Avoid adding functions to this module whenever possible,
+  # instead prefer defining modules closer to the context they are used.
   @moduledoc false
 
   @doc """