Clarify the dual access syntax for maps and mention structs

Author: josevalim

lib/elixir/lib/map.ex

@@ -26,8 +26,8 @@ defmodule Map do
       %{:a => 1, :b => 2, "hello" => "world"}
 
   Keys in maps can be accessed through some of the functions in this module
-  (such as `Map.get/3` or `Map.fetch/2`) or through the `[]` syntax provided by
-  the `Access` module:
+  (such as `Map.get/3` or `Map.fetch/2`) or through the `map[]` syntax provided
+  by the `Access` module:
 
       iex> map = %{a: 1, b: 2}
       iex> Map.fetch(map, :a)
@@ -37,18 +37,23 @@ defmodule Map do
       iex> map["non_existing_key"]
       nil
 
-  The alternative access syntax `map.key` is provided alongside `[]` when the
-  map has a `:key` key; note that while `map[key]` will return `nil` if `map`
-  doesn't contain `key`, `map.key` will raise if `map` doesn't contain
-  the key `:key`.
+  For accessing atom keys, one may also `map.key`. Note that while `map[key]` will
+  return `nil` if `map` doesn't contain `key`, `map.key` will raise if `map` doesn't
+  contain the key `:key`.
 
       iex> map = %{foo: "bar", baz: "bong"}
       iex> map.foo
       "bar"
       iex> map.non_existing_key
       ** (KeyError) key :non_existing_key not found in: %{baz: "bong", foo: "bar"}
 
-  Maps can be pattern matched on; when a map is on the left-hand side of a
+  The two syntaxes for accessing keys reveal the dual nature of maps. The `map[key]`
+  syntax is used for dynamically created maps that may have any key, of any type.
+  `map.key` is used with maps that hold a predetermined set of atoms keys, which are
+  expected to always be present. Structs, defined via `defstruct/1`, are one example
+  of such "static maps", where the keys can also be checked during compile time.
+
+  Maps can be pattern matched on. When a map is on the left-hand side of a
   pattern match, it will match if the map on the right-hand side contains the
   keys on the left-hand side and their values match the ones on the left-hand
   side. This means that an empty map matches every map.