Improve docs for Macro.inspect_atom/2

1 files changed, 15 insertions, 3 deletions

diff --git a/lib/elixir/lib/macro.ex b/lib/elixir/lib/macro.ex
index b5fe73bdd..a18eac0db 100644
--- a/lib/elixir/lib/macro.ex
+++ b/lib/elixir/lib/macro.ex
@@ -1980,16 +1980,20 @@ defmodule Macro do
   end
 
   @doc ~S"""
-  Inspects the given atom.
+  Inspects `atom` according to different source formats.
 
-  The atom can be inspected as a literal (`:literal`),
-  as a key (`:key`), or as the function name in a remote call
+  The atom can be inspected according to the three different
+  formats it appears in source code: as a literal (`:literal`),
+  as a key (`:key`), or as the function name of a remote call
   (`:remote_call`).
 
   ## Examples
 
   ### As a literal
 
+  Literals include regular atoms, quoted atoms, operators,
+  aliases, and the special `nil`, `true`, and `false` atoms.
+
       iex> Macro.inspect_atom(:literal, nil)
       "nil"
       iex> Macro.inspect_atom(:literal, :foo)
@@ -1998,11 +2002,15 @@ defmodule Macro do
       ":<>"
       iex> Macro.inspect_atom(:literal, :Foo)
       ":Foo"
+      iex> Macro.inspect_atom(:literal, Foo.Bar)
+      "Foo.Bar"
       iex> Macro.inspect_atom(:literal, :"with spaces")
       ":\"with spaces\""
 
   ### As a key
 
+  Inspect an atom as a key of a keyword list or a map.
+
       iex> Macro.inspect_atom(:key, :foo)
       "foo:"
       iex> Macro.inspect_atom(:key, :<>)
@@ -2014,6 +2022,8 @@ defmodule Macro do
 
   ### As a remote call
 
+  Inspect an atom the function name of a remote call.
+
       iex> Macro.inspect_atom(:remote_call, :foo)
       "foo"
       iex> Macro.inspect_atom(:remote_call, :<>)
@@ -2026,6 +2036,8 @@ defmodule Macro do
   """
   @doc since: "1.14.0"
   @spec inspect_atom(:literal | :key | :remote_call, atom) :: binary
+  def inspect_atom(source_format, atom)
+
   def inspect_atom(:literal, atom) when is_nil(atom) or is_boolean(atom) do
     Atom.to_string(atom)
   end