entc: improve generated comments for edges and fields (#2632)

* replace default field comment with user comment if defined
* use comments defined on edges in generated entities
* add docs for comment method on edges and fields
* update integration to reflect above changes

entc/integration/config/ent/schema/user.go

@@ -44,7 +44,8 @@ func (User) Fields() []ent.Field {
 			Optional().
 			Annotations(entsql.Annotation{
 				Size: 128,
-			}).Comment(`Comment line1
+			}).Comment(`Name of the user.
+Comment line1
 Comment line2`),
 		field.String("label").
 			Optional(),

entc/integration/config/ent/user.go

@@ -19,7 +19,7 @@ type User struct {
 	config `json:"-"`
 	// ID of the ent.
 	ID int `json:"id,omitempty"`
-	// Name holds the value of the "name" field.
+	// Name of the user.
 	// Comment line1
 	// Comment line2
 	Name string `json:"name,omitempty"`

entc/integration/edgeschema/ent/tweet.go

@@ -26,7 +26,7 @@ type Tweet struct {
 type TweetEdges struct {
 	// LikedUsers holds the value of the liked_users edge.
 	LikedUsers []*User `json:"liked_users,omitempty"`
-	// User holds the value of the user edge.
+	// The uniqueness is enforced on the edge schema
 	User []*User `json:"user,omitempty"`
 	// Likes holds the value of the likes edge.
 	Likes []*TweetLike `json:"likes,omitempty"`

entc/integration/ent/card.go

@@ -29,8 +29,7 @@ type Card struct {
 	Balance float64 `json:"balance,omitempty"`
 	// Number holds the value of the "number" field.
 	Number string `json:"-"`
-	// Name holds the value of the "name" field.
-	// Exact name written on card
+	// Name exactly as written on card.
 	Name string `json:"name,omitempty"`
 	// Edges holds the relations/edges for other nodes in the graph.
 	// The values are being populated by the CardQuery when eager-loading is set.
@@ -43,7 +42,7 @@ type Card struct {
 
 // CardEdges holds the relations/edges for other nodes in the graph.
 type CardEdges struct {
-	// Owner holds the value of the owner edge.
+	// Owner of the card. O2O inverse edge
 	Owner *User `json:"owner,omitempty"`
 	// Spec holds the value of the spec edge.
 	Spec []*Spec `json:"spec,omitempty"`

entc/integration/ent/group.go

@@ -29,8 +29,7 @@ type Group struct {
 	Type *string `json:"type,omitempty"`
 	// MaxUsers holds the value of the "max_users" field.
 	MaxUsers int `json:"max_users,omitempty"`
-	// Name holds the value of the "name" field.
-	// field with multiple validators
+	// Name field with multiple validators
 	Name string `json:"name,omitempty"`
 	// Edges holds the relations/edges for other nodes in the graph.
 	// The values are being populated by the GroupQuery when eager-loading is set.

entc/integration/ent/schema/card.go

@@ -67,7 +67,7 @@ func (Card) Fields() []ent.Field {
 			}),
 		field.String("name").
 			Optional().
-			Comment("Exact name written on card").
+			Comment("Name exactly as written on card.").
 			NotEmpty().
 			Annotations(&template.Extension{
 				Type: "string",
@@ -79,7 +79,7 @@ func (Card) Fields() []ent.Field {
 func (Card) Edges() []ent.Edge {
 	return []ent.Edge{
 		edge.From("owner", User.Type).
-			Comment("O2O inverse edge").
+			Comment("Owner of the card. O2O inverse edge").
 			Ref("card").
 			Unique(),
 		edge.From("spec", Spec.Type).

entc/integration/ent/schema/group.go

@@ -43,7 +43,7 @@ func (Group) Fields() []ent.Field {
 			Positive().
 			Default(10),
 		field.String("name").
-			Comment("field with multiple validators").
+			Comment("Name field with multiple validators").
 			Match(regexp.MustCompile("[a-zA-Z_]+$")).
 			Validate(func(s string) error {
 				if strings.ToLower(s) == s {

entc/integration/ent/schema/user.go

@@ -57,7 +57,7 @@ func (User) Fields() []ent.Field {
 // Edges of the user.
 func (User) Edges() []ent.Edge {
 	return []ent.Edge{
-		edge.To("card", Card.Type).Comment("O2O edge").Unique(),
+		edge.To("card", Card.Type).Comment("Cards associated with this user. O2O edge").Unique(),
 		edge.To("pets", Pet.Type),
 		edge.To("files", File.Type),
 		edge.To("groups", Group.Type),

entc/integration/ent/user.go

@@ -53,7 +53,7 @@ type User struct {
 
 // UserEdges holds the relations/edges for other nodes in the graph.
 type UserEdges struct {
-	// Card holds the value of the card edge.
+	// Cards associated with this user. O2O edge
 	Card *Card `json:"card,omitempty"`
 	// Pets holds the value of the pets edge.
 	Pets []*Pet `json:"pets,omitempty"`

entc/integration/gremlin/ent/card.go

@@ -28,8 +28,7 @@ type Card struct {
 	Balance float64 `json:"balance,omitempty"`
 	// Number holds the value of the "number" field.
 	Number string `json:"-"`
-	// Name holds the value of the "name" field.
-	// Exact name written on card
+	// Name exactly as written on card.
 	Name string `json:"name,omitempty"`
 	// Edges holds the relations/edges for other nodes in the graph.
 	// The values are being populated by the CardQuery when eager-loading is set.
@@ -40,7 +39,7 @@ type Card struct {
 
 // CardEdges holds the relations/edges for other nodes in the graph.
 type CardEdges struct {
-	// Owner holds the value of the owner edge.
+	// Owner of the card. O2O inverse edge
 	Owner *User `json:"owner,omitempty"`
 	// Spec holds the value of the spec edge.
 	Spec []*Spec `json:"spec,omitempty"`

entc/integration/gremlin/ent/group.go

@@ -28,8 +28,7 @@ type Group struct {
 	Type *string `json:"type,omitempty"`
 	// MaxUsers holds the value of the "max_users" field.
 	MaxUsers int `json:"max_users,omitempty"`
-	// Name holds the value of the "name" field.
-	// field with multiple validators
+	// Name field with multiple validators
 	Name string `json:"name,omitempty"`
 	// Edges holds the relations/edges for other nodes in the graph.
 	// The values are being populated by the GroupQuery when eager-loading is set.

entc/integration/gremlin/ent/user.go

@@ -50,7 +50,7 @@ type User struct {
 
 // UserEdges holds the relations/edges for other nodes in the graph.
 type UserEdges struct {
-	// Card holds the value of the card edge.
+	// Cards associated with this user. O2O edge
 	Card *Card `json:"card,omitempty"`
 	// Pets holds the value of the pets edge.
 	Pets []*Pet `json:"pets,omitempty"`

entc/integration/hooks/ent/card.go

@@ -23,13 +23,11 @@ type Card struct {
 	ID int `json:"id,omitempty"`
 	// Number holds the value of the "number" field.
 	Number string `json:"number,omitempty"`
-	// Name holds the value of the "name" field.
 	// Exact name written on card
 	Name string `json:"name,omitempty"`
 	// CreatedAt holds the value of the "created_at" field.
 	CreatedAt time.Time `json:"created_at,omitempty"`
-	// InHook holds the value of the "in_hook" field.
-	// A mandatory field that is set by the hook
+	// InHook is a mandatory field that is set by the hook.
 	InHook string `json:"in_hook,omitempty"`
 	// Edges holds the relations/edges for other nodes in the graph.
 	// The values are being populated by the CardQuery when eager-loading is set.

entc/integration/hooks/ent/internal/schema.go

@@ -10,4 +10,4 @@
 // Package internal holds a loadable version of the latest schema.
 package internal
 
-const Schema = `{"Schema":"entgo.io/ent/entc/integration/hooks/ent/schema","Package":"entgo.io/ent/entc/integration/hooks/ent","Schemas":[{"name":"Card","config":{"Table":""},"edges":[{"name":"owner","type":"User","ref_name":"cards","unique":true,"inverse":true}],"fields":[{"name":"number","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"default":true,"default_value":"unknown","default_kind":24,"immutable":true,"validators":1,"position":{"Index":0,"MixedIn":false,"MixinIndex":0}},{"name":"name","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"optional":true,"position":{"Index":1,"MixedIn":false,"MixinIndex":0},"comment":"Exact name written on card"},{"name":"created_at","type":{"Type":2,"Ident":"","PkgPath":"time","PkgName":"","Nillable":false,"RType":null},"default":true,"default_kind":19,"position":{"Index":2,"MixedIn":false,"MixinIndex":0}},{"name":"in_hook","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"position":{"Index":3,"MixedIn":false,"MixinIndex":0},"comment":"A mandatory field that is set by the hook"}],"hooks":[{"Index":0,"MixedIn":true,"MixinIndex":0},{"Index":0,"MixedIn":false,"MixinIndex":0},{"Index":1,"MixedIn":false,"MixinIndex":0}]},{"name":"User","config":{"Table":""},"edges":[{"name":"cards","type":"Card"},{"name":"friends","type":"User"},{"name":"best_friend","type":"User","unique":true}],"fields":[{"name":"version","type":{"Type":12,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"default":true,"default_value":0,"default_kind":2,"position":{"Index":0,"MixedIn":true,"MixinIndex":0}},{"name":"name","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"position":{"Index":0,"MixedIn":false,"MixinIndex":0}},{"name":"worth","type":{"Type":17,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"optional":true,"position":{"Index":1,"MixedIn":false,"MixinIndex":0}},{"name":"password","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"optional":true,"position":{"Index":2,"MixedIn":false,"MixinIndex":0},"sensitive":true}],"hooks":[{"Index":0,"MixedIn":true,"MixinIndex":0},{"Index":0,"MixedIn":false,"MixinIndex":0}]}],"Features":["schema/snapshot"]}`
+const Schema = `{"Schema":"entgo.io/ent/entc/integration/hooks/ent/schema","Package":"entgo.io/ent/entc/integration/hooks/ent","Schemas":[{"name":"Card","config":{"Table":""},"edges":[{"name":"owner","type":"User","ref_name":"cards","unique":true,"inverse":true}],"fields":[{"name":"number","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"default":true,"default_value":"unknown","default_kind":24,"immutable":true,"validators":1,"position":{"Index":0,"MixedIn":false,"MixinIndex":0}},{"name":"name","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"optional":true,"position":{"Index":1,"MixedIn":false,"MixinIndex":0},"comment":"Exact name written on card"},{"name":"created_at","type":{"Type":2,"Ident":"","PkgPath":"time","PkgName":"","Nillable":false,"RType":null},"default":true,"default_kind":19,"position":{"Index":2,"MixedIn":false,"MixinIndex":0}},{"name":"in_hook","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"position":{"Index":3,"MixedIn":false,"MixinIndex":0},"comment":"InHook is a mandatory field that is set by the hook."}],"hooks":[{"Index":0,"MixedIn":true,"MixinIndex":0},{"Index":0,"MixedIn":false,"MixinIndex":0},{"Index":1,"MixedIn":false,"MixinIndex":0}]},{"name":"User","config":{"Table":""},"edges":[{"name":"cards","type":"Card"},{"name":"friends","type":"User"},{"name":"best_friend","type":"User","unique":true}],"fields":[{"name":"version","type":{"Type":12,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"default":true,"default_value":0,"default_kind":2,"position":{"Index":0,"MixedIn":true,"MixinIndex":0}},{"name":"name","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"position":{"Index":0,"MixedIn":false,"MixinIndex":0}},{"name":"worth","type":{"Type":17,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"optional":true,"position":{"Index":1,"MixedIn":false,"MixinIndex":0}},{"name":"password","type":{"Type":7,"Ident":"","PkgPath":"","PkgName":"","Nillable":false,"RType":null},"optional":true,"position":{"Index":2,"MixedIn":false,"MixinIndex":0},"sensitive":true}],"hooks":[{"Index":0,"MixedIn":true,"MixinIndex":0},{"Index":0,"MixedIn":false,"MixinIndex":0}]}],"Features":["schema/snapshot"]}`

entc/integration/hooks/ent/schema/card.go

@@ -83,7 +83,7 @@ func (Card) Fields() []ent.Field {
 		field.Time("created_at").
 			Default(time.Now),
 		field.String("in_hook").
-			Comment("A mandatory field that is set by the hook"),
+			Comment("InHook is a mandatory field that is set by the hook."),
 	}
 }
 

entc/integration/migrate/versioned/group.go

@@ -74,11 +74,11 @@ func (gr *Group) Update() *GroupUpdateOne {
 // Unwrap unwraps the Group entity that was returned from a transaction after it was closed,
 // so that all future queries will be executed through the driver which created the transaction.
 func (gr *Group) Unwrap() *Group {
-	tx, ok := gr.config.driver.(*txDriver)
+	_tx, ok := gr.config.driver.(*txDriver)
 	if !ok {
 		panic("versioned: Group is not a transactional entity")
 	}
-	gr.config.driver = tx.drv
+	gr.config.driver = _tx.drv
 	return gr
 }