Define how to_existing_atom works within modules, closes #11786

Author: josevalim

lib/elixir/lib/list.ex

@@ -949,14 +949,22 @@ defmodule List do
   end
 
   @doc """
-  Converts a charlist to an existing atom. Raises an `ArgumentError`
-  if the atom does not exist.
+  Converts a charlist to an existing atom.
 
   Elixir supports conversions from charlists which contains any Unicode
-  code point.
+  code point. Raises an `ArgumentError` if the atom does not exist.
 
   Inlined by the compiler.
 
+  > #### Atoms and modules {: .info}
+  >
+  > Since Elixir is a compiled language, the atoms defined in a module
+  > will only exist after said module is loaded, which typically happens
+  > whenever a function in the module is executed. Therefore, it is
+  > generally recommended to call `List.to_existing_atom/1` only to
+  > convert atoms defined within the module making the function call
+  > to `to_existing_atom/1`.
+
   ## Examples
 
       iex> _ = :my_atom

lib/elixir/lib/string.ex

@@ -2569,9 +2569,19 @@ defmodule String do
   Converts a string to an existing atom.
 
   The maximum atom size is of 255 Unicode code points.
+  Raises an `ArgumentError` if the atom does not exist.
 
   Inlined by the compiler.
 
+  > #### Atoms and modules {: .info}
+  >
+  > Since Elixir is a compiled language, the atoms defined in a module
+  > will only exist after said module is loaded, which typically happens
+  > whenever a function in the module is executed. Therefore, it is
+  > generally recommended to call `String.to_existing_atom/1` only to
+  > convert atoms defined within the module making the function call
+  > to `to_existing_atom/1`.
+
   ## Examples
 
       iex> _ = :my_atom