From 52305c18346df5f108c8d35112fb2f52d605a75b Mon Sep 17 00:00:00 2001
From: Ariel Mashraki <7413593+a8m@users.noreply.github.com>
Date: Thu, 25 Jun 2020 23:17:20 +0300
Subject: [PATCH] doc: add a mutation section for crud interface (#570)

---
 doc/md/crud.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/doc/md/crud.md b/doc/md/crud.md
index d69ada454..d53cc55de 100755
--- a/doc/md/crud.md
+++ b/doc/md/crud.md
@@ -261,4 +261,55 @@ err := client.File.
 	Delete().
 	Where(file.UpdatedAtLT(date))
 	Exec(ctx)
+```
+
+## Mutation
+
+Each generated node type has its own type of mutation. For example, all [`User` builders](crud.md#create-an-entity), share
+the same generated `UserMutation` object.
+However, all builder types implement the generic <a target="_blank" href="https://godoc.org/github.com/facebookincubator/ent#Mutation">`ent.Mutation`<a> interface.
+
+For example, in order to write a generic code that apply a set of methods on both `ent.UserCreate`
+and `ent.UserUpdate`, use the `UserMutation` object:
+
+```go
+func Do() {
+    creator := client.User.Create()
+    SetAgeName(creator.Mutation())
+	updater := client.User.UpdateOneID(id)
+	SetAgeName(updater.Mutation())
+}
+
+// SetAgeName sets the age and the name for any mutation.
+func SetAgeName(m *ent.UserMutation) {
+    m.SetAge(32)
+    m.SetName("Ariel")
+}
+```
+
+In some cases, you want to apply a set of methods on multiple types.
+For cases like this, either use the generic `ent.Mutation` interface,
+or create your own interface.
+
+```go
+func Do() {
+	creator1 := client.User.Create()
+	SetName(creator1.Mutation(), "a8m")
+
+	creator2 := client.Pet.Create()
+	SetName(creator2.Mutation(), "pedro")
+}
+
+// SetNamer wraps the 2 methods for getting
+// and setting the "name" field in mutations.
+type SetNamer interface {
+	SetName(string)
+	Name() (string, bool)
+}
+
+func SetName(m SetNamer, name string) {
+    if _, exist := m.Name(); !exist {
+    	m.SetName(name)
+    }
+}
 ```
\ No newline at end of file