Improve documentation on charlists (#9294)

1 files changed, 15 insertions, 2 deletions

diff --git a/lib/elixir/lib/list.ex b/lib/elixir/lib/list.ex
index 9c06e23fd..193f3afaf 100644
--- a/lib/elixir/lib/list.ex
+++ b/lib/elixir/lib/list.ex
@@ -88,10 +88,23 @@ defmodule List do
       iex> 'abc'
       'abc'
 
+  Even though the representation changed, the raw data does remain a list of
+  numbers, which can be handled as such:
+
+      iex> inspect('abc', charlists: :as_list)
+      "[97, 98, 99]"
+      iex> Enum.map('abc', fn num -> 1000 + num end)
+      [1097, 1098, 1099]
+
+  You can use the `IEx.Helpers.i/1` helper to get a condensed rundown on
+  charlists in IEx when you encounter them, which shows you the type, description
+  and also the raw representation in one single summary.
+
   The rationale behind this behaviour is to better support
   Erlang libraries which may return text as charlists
-  instead of Elixir strings. One example of such functions
-  is `Application.loaded_applications/0`:
+  instead of Elixir strings. In Erlang, charlists are the default
+  way of handling strings, while in Elixir it's binaries. One
+  example of such functions is `Application.loaded_applications/0`:
 
       Application.loaded_applications()
       #=>  [