Provide references on structs for more information, closes #13664

Author: josevalim

lib/elixir/lib/kernel.ex

@@ -5326,13 +5326,10 @@ defmodule Kernel do
 
   A struct is a tagged map that allows developers to provide
   default values for keys, tags to be used in polymorphic
-  dispatches and compile time assertions. For more information
-  about structs, please check `%/2`.
+  dispatches and compile time assertions.
 
   It is only possible to define a struct per module, as the
-  struct is tied to the module itself. Calling `defstruct/1`
-  also defines a `__struct__/0` function that returns the
-  struct itself.
+  struct is tied to the module itself.
 
   ## Examples
 
@@ -5366,6 +5363,13 @@ defmodule Kernel do
         defstruct [:title, :content, :author]
       end
 
+  Once a struct is defined, it is possible to create them as follows:
+
+      %Post{title: "Hello world!"}
+
+  For more information on creating, updating, and pattern matching on
+  structs, please check `%/2`.
+
   ## Deriving
 
   Although structs are maps, by default structs do not implement

lib/elixir/lib/kernel/special_forms.ex

@@ -112,26 +112,24 @@ defmodule Kernel.SpecialForms do
 
       %User{age: age} = user
 
-  An update operation specific for structs is also available:
-
-      %User{user | age: 28}
-
   The advantage of structs is that they validate that the given
   keys are part of the defined struct. The example below will fail
   because there is no key `:full_name` in the `User` struct:
 
       %User{full_name: "john doe"}
 
-  The syntax above will guarantee the given keys are valid at
-  compilation time and it will guarantee at runtime the given
-  argument is a struct, failing with `BadStructError` otherwise.
+  An update operation specific for structs is also available:
+
+      %User{user | age: 28}
+
+  Once again, the syntax above will guarantee the given keys
+  are valid at compilation time and it will guarantee at runtime
+  the given argument is a struct, failing with `BadStructError`
+  otherwise. The map update syntax can also be used for updating
+  structs, and it is useful when you want to update any struct,
+  regardless of their name, as long as they have matching fields:
 
-  Although structs are maps, by default structs do not implement
-  any of the protocols implemented for maps. Check
-  `Kernel.defprotocol/2` for more information on how structs
-  can be used with protocols for polymorphic dispatch. Also
-  see `Kernel.struct/2` and `Kernel.struct!/2` for examples on
-  how to create and update structs dynamically.
+      %{user | age: 28}
 
   ## Pattern matching on struct names
 

lib/elixir/pages/getting-started/structs.md

@@ -69,6 +69,8 @@ iex> %User{} = %{}
 ** (MatchError) no match of right hand side value: %{}
 ```
 
+For more details on creating, updating, and pattern matching structs, see the documentation for `%/2`.
+
 ## Structs are bare maps underneath
 
 Structs are simply maps with a "special" field named `__struct__` that holds the name of the struct: