schema: add Comment annotation (#3164)

* Add schema.CommentAnnotation (resolves #3155)

Adds new mechanism for customizing a model's godoc comment in code (via an Annotation).

* feedback

entc/gen/template/ent.tmpl

@@ -19,7 +19,7 @@ import (
 	{{- end }}
 )
 
-// {{ $.Name }} is the model entity for the {{ $.Name }} schema.
+{{ template "model/comment" $ }}
 {{- with $tmpls := matchTemplate "model/comment/additional/*" }}
 	{{- range $tmpl := $tmpls }}
 		{{- xtemplate $tmpl $ }}
@@ -185,6 +185,17 @@ func ({{ $receiver }} {{ $slice }}) config(cfg config) {
 	}
 {{ end }}
 
+{{/* A template for generating the Entity's comment. */}}
+{{- define "model/comment" }}
+	{{- if and $.Annotations.Comment $.Annotations.Comment.Text }}
+		{{- range $line := split $.Annotations.Comment.Text "\n" }}
+			// {{ $line }}
+		{{- end }}
+	{{- else }}
+		// {{ $.Name }} is the model entity for the {{ $.Name }} schema.
+	{{- end }}
+{{- end }}
+
 {{/* A template for generating the tag of the Edges struct-field. */}}
 {{- define "model/edgetags" }}
 	{{- $tag := `json:"edges"` }}

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

@@ -6,6 +6,7 @@ package schema
 
 import (
 	"entgo.io/ent"
+	"entgo.io/ent/schema"
 	"entgo.io/ent/schema/edge"
 	"entgo.io/ent/schema/field"
 )
@@ -15,6 +16,13 @@ type User struct {
 	ent.Schema
 }
 
+// Annotations of the User.
+func (User) Annotations() []schema.Annotation {
+	return []schema.Annotation{
+		schema.Comment("User represents a user who has Pets and Friends."),
+	}
+}
+
 // Fields of the User.
 func (User) Fields() []ent.Field {
 	return []ent.Field{

entc/integration/template/ent/user.go

@@ -14,7 +14,7 @@ import (
 	"entgo.io/ent/entc/integration/template/ent/user"
 )
 
-// User is the model entity for the User schema.
+// User represents a user who has Pets and Friends.
 type User struct {
 	config `json:"-"`
 	// ID of the ent.

schema/schema.go

@@ -22,3 +22,22 @@ type Annotation interface {
 type Merger interface {
 	Merge(Annotation) Annotation
 }
+
+// CommentAnnotation is a builtin schema annotation for
+// configuring the schema's Godoc comment.
+type CommentAnnotation struct {
+	Text string // Comment text.
+}
+
+// Name implements the Annotation interface.
+func (c *CommentAnnotation) Name() string {
+	return "Comment"
+}
+
+// Comment is a builtin schema annotation for
+// configuring the schema's Godoc comment.
+func Comment(text string) *CommentAnnotation {
+	return &CommentAnnotation{Text: text}
+}
+
+var _ Annotation = (*CommentAnnotation)(nil)