Clarify call syntax for Keyword, closes #9645

1 files changed, 52 insertions, 44 deletions

diff --git a/lib/elixir/lib/keyword.ex b/lib/elixir/lib/keyword.ex
index 6cd1473bb..f52bdf6e3 100644
--- a/lib/elixir/lib/keyword.ex
+++ b/lib/elixir/lib/keyword.ex
@@ -4,6 +4,8 @@ defmodule Keyword do
   element of the tuple is an atom and the second element can be any
   value, used mostly to work with optional values.
 
+  ## Examples
+
   For example, the following is a keyword list:
 
       [{:exit_on_close, true}, {:active, :once}, {:packet_size, 1024}]
@@ -13,62 +15,68 @@ defmodule Keyword do
 
       [exit_on_close: true, active: :once, packet_size: 1024]
 
-  This is also the syntax that Elixir uses to inspect keyword lists:
-
-      iex> [{:active, :once}]
-      [active: :once]
-
-  The two syntaxes are completely equivalent. Like atoms, keywords
-  must be composed of Unicode characters such as letters, numbers,
-  underscore, and `@`. If the keyword has a character that does not
-  belong to the category above, such as spaces, you can wrap it in
-  quotes:
+  The two syntaxes are completely equivalent. Like atoms, keyword
+  lists keys must be composed of Unicode characters such as letters,
+  numbers, underscore, and `@`. If the keyword has a character that
+  does not belong to the category above, such as spaces, you can wrap
+  it in quotes:
 
       iex> ["exit on close": true]
       ["exit on close": true]
 
-  Wrapping a keyword in quotes does not make it a string. Keywords are
-  always atoms. If you use quotes when all characters are a valid part
-  of a keyword without quotes, Elixir will warn.
+  Wrapping a keyword in quotes does not make it a string. Keyword lists
+  keys are always atoms. If you use quotes around the key when quoting
+  is not necessary, Elixir will warn.
 
-  Note that when keyword lists are passed as the last argument to a function,
-  if the shorthand syntax is used then the square brackets around the keyword
-  list can be omitted as well. For example, the following:
+  ## Duplicate keys and ordering
 
-      String.split("1-0", "-", trim: true, parts: 2)
+  A keyword may have duplicated keys so it is not strictly a key-value
+  data type. However most of the functions in this module behave exactly
+  as a key-value so they work similarly to the functions you would find
+  in the `Map` module. For example, `Keyword.get/3` will get the first
+  entry matching the given key, regardless if duplicated entries exist.
+  Similarly, `Keyword.put/3` and `Keyword.delete/2` ensure all duplicated
+  entries for a given key are removed when invoked. Note however that
+  keyword list operations need to traverse the list in order to find
+  keys, so these operations are slower than their map counterparts.
 
-  is equivalent to:
+  A handful of functions exist to handle duplicated keys, for example,
+  `get_values/2` returns all values for a given key and `delete_first/2`
+  deletes just one of the existing entries.
 
-      String.split("1-0", "-", [trim: true, parts: 2])
-
-  A keyword may have duplicated keys so it is not strictly
-  a key-value store. However most of the functions in this module
-  behave exactly as a key-value so they work similarly to
-  the functions you would find in the `Map` module.
-
-  For example, `Keyword.get/3` will get the first entry matching
-  the given key, regardless if duplicated entries exist.
-  Similarly, `Keyword.put/3` and `Keyword.delete/2` ensure all
-  duplicated entries for a given key are removed when invoked.
-  Note that operations that require keys to be found in the keyword
-  list (like `Keyword.get/3`) need to traverse the list in order
-  to find keys, so these operations may be slower than their map
-  counterparts.
-
-  A handful of functions exist to handle duplicated keys, in
-  particular, `Enum.into/2` allows creating new keywords without
-  removing duplicated keys, `get_values/2` returns all values for
-  a given key and `delete_first/2` deletes just one of the existing
-  entries.
-
-  The functions in `Keyword` do not guarantee any property when
-  it comes to ordering. However, since a keyword list is simply a
-  list, all the operations defined in `Enum` and `List` can be
-  applied too, especially when ordering is required.
+  The functions in `Keyword` do not guarantee any property when it comes
+  to ordering. However, since a keyword list is simply a list, all the
+  operations defined in `Enum` and `List` can be applied too, especially
+  when ordering is required.
 
   Most of the functions in this module work in linear time. This means
   that, the time it takes to perform an operation grows at the same
   rate as the length of the list.
+
+  ## Call syntax
+
+  When keyword lists are passed as the last argument to a function, then
+  the square brackets around the keyword list can be omitted as well. For
+  example, the keyword list syntax:
+
+      String.split("1-0", "-", [trim: true, parts: 2])
+
+  can be written without the enclosing brackets whenever it is the last
+  argument of a function call:
+
+      String.split("1-0", "-", trim: true, parts: 2)
+
+  Since tuples, lists, maps, and others are treated the same as function
+  calls in Elixir syntax, this property is also available to them:
+
+      iex> {1, 2, foo: :bar}
+      {1, 2, [{:foo, :bar}]}
+
+      iex> [1, 2, foo: :bar]
+      [1, 2, {:foo, :bar}]
+
+      iex> %{1 => 2, foo: :bar}
+      %{1 => 2, :foo => :bar}
   """
 
   @compile :inline_list_funcs