From d7b3a6c4f4dc537d0ca7e5efc6a0bf09f086fa3c Mon Sep 17 00:00:00 2001
From: Ariel Mashraki <7413593+a8m@users.noreply.github.com>
Date: Tue, 23 May 2023 14:54:18 +0300
Subject: [PATCH] ent: document ent.Value returned by mutations (#3556)

Fixed https://github.com/ent/ent/issues/3471
---
 ent.go | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/ent.go b/ent.go
index 2c276b5c70..0250d6d27a 100644
--- a/ent.go
+++ b/ent.go
@@ -239,7 +239,7 @@ func (Schema) Policy() Policy { return nil }
 func (Schema) Annotations() []schema.Annotation { return nil }
 
 type (
-	// Value represents a value returned by ent.
+	// Value represents a dynamic value returned by mutations or queries.
 	Value any
 
 	// Mutation represents an operation that mutate the graph.
@@ -328,7 +328,14 @@ type (
 
 	// Mutator is the interface that wraps the Mutate method.
 	Mutator interface {
-		// Mutate apply the given mutation on the graph.
+		// Mutate apply the given mutation on the graph. The returned
+		// ent.Value is changing according to the mutation operation:
+		//
+		// OpCreate, the returned value is the created node (T).
+		// OpUpdateOne, the returned value is the updated node (T).
+		// OpUpdate, the returned value is the amount of updated nodes (int).
+		// OpDeleteOne, OpDelete, the returned value is the amount of deleted nodes (int).
+		//
 		Mutate(context.Context, Mutation) (Value, error)
 	}