Documentation tweaks for changesets and embedded schemas (#4582)

Author: jdmarshall

lib/ecto/changeset.ex

@@ -1,14 +1,17 @@
 defmodule Ecto.Changeset do
   @moduledoc ~S"""
   Changesets allow filtering, casting, validation and
-  definition of constraints when manipulating structs.
-
-  There is an example of working with changesets in the introductory
-  documentation in the `Ecto` module. The functions `cast/4` and
-  `change/2` are the usual entry points for creating changesets.
-  The first one is used to cast and validate external parameters,
-  such as parameters sent through a form, API, command line, etc.
-  The second one is used to change data directly from your application.
+  definition of constraints when manipulating structs, usually in
+  preparation for inserting and updating entries into a database.
+
+  There is an example of
+  [working with changesets](`Ecto#module-changesets`) in the
+  introductory documentation in the `Ecto` module. In a nutshell, there
+  are two main functions for creating a changeset. The `cast/4` function
+  is used to receive external parameters from a form, API or command
+  line, and convert them to the types defined in your `Ecto.Schema`.
+  `change/2` is used to modify data directly from your application,
+  assuming the data given is valid and matches the existing types.
 
   The remaining functions in this module, such as validations,
   constraints, association handling, are about manipulating
@@ -18,14 +21,14 @@ defmodule Ecto.Changeset do
 
   Changesets allow working with two kinds of data:
 
-    * internal to the application - for example programmatically generated,
-      or coming from other subsystems. This use case is primarily covered
-      by the `change/2` and `put_change/3` functions.
-
-    * external to the application - for example data provided by the user in
+    * external to the application - for example user input from
       a form that needs to be type-converted and properly validated. This
       use case is primarily covered by the `cast/4` function.
 
+   * internal to the application - for example programmatically generated,
+      or coming from other subsystems. This use case is primarily covered
+      by the `change/2` and `put_change/3` functions.
+
   When working with external data, the data is typically provided
   as maps with string keys (also known as parameters). On the other hand,
   when working with internal data, you typically have maps of atom keys
@@ -147,8 +150,8 @@ defmodule Ecto.Changeset do
 
   ## Associations, embeds, and on replace
 
-  Using changesets you can work with associations as well as with embedded
-  structs. There are two primary APIs:
+  Using changesets you can work with associations as well as with
+  [embedded](embedded-schemas.html) structs. There are two primary APIs:
 
     * `cast_assoc/3` and `cast_embed/3` - those functions are used when
       working with external data. In particular, they allow you to change