Update docs, remove Multi guide (#4619)

Author: wojtekmach

guides/howtos/Composable transactions with Multi.md

@@ -74,10 +74,10 @@ if changeset.valid? do
   account = Registration.to_account(registration)
   profile = Registration.to_profile(registration)
 
-  MyApp.Repo.transaction fn ->
-    MyApp.Repo.insert_all "accounts", [account]
-    MyApp.Repo.insert_all "profiles", [profile]
-  end
+  MyApp.Repo.transact(fn ->
+    MyApp.Repo.insert_all("accounts", [account])
+    MyApp.Repo.insert_all("profiles", [profile])
+  end)
 
   {:ok, registration}
 else

guides/howtos/Data mapping and validation.md

@@ -340,14 +340,14 @@ defmodule Ecto do
   Another function in `Ecto` is `build_assoc/3`, which allows
   someone to build an associated struct with the proper fields:
 
-      Repo.transaction fn ->
+      Repo.transact(fn ->
         post = Repo.insert!(%Post{title: "Hello", body: "world"})
 
         # Build a comment from post
         comment = Ecto.build_assoc(post, :comments, body: "Excellent!")
 
         Repo.insert!(comment)
-      end
+      end)
 
   In the example above, `Ecto.build_assoc/3` is equivalent to:
 

lib/ecto.ex

@@ -18,6 +18,13 @@ defmodule Ecto.Multi do
   `Ecto.Multi.to_list/1` returns a canonical representation of the
   structure that can be used for introspection.
 
+  > #### When to use Ecto.Multi? {: .info}
+
+  > `Ecto.Multi` is particularly useful when the set of operations to perform
+  > is dynamic. For most use cases, however, using regular control flow within
+  > [`Repo.transact(fun)`](`c:Ecto.Repo.transact/2`) and returning
+  > `{:ok, result}` or `{:error, reason}` is more straightforward.
+
   ## Changesets
 
   If multi contains operations that accept changesets (like `insert/4`,