From 55ed0508c7bfc3c3bd712e061bdc4b95a765208f Mon Sep 17 00:00:00 2001 From: Ariel Mashraki <7413593+a8m@users.noreply.github.com> Date: Thu, 24 Mar 2022 12:42:57 +0200 Subject: [PATCH] doc: minor impronments to getting-started (#2422) --- doc/md/getting-started.md | 36 ++++++++++++++---------------------- doc/md/hooks.md | 2 +- examples/start/start.go | 37 ++++++++++++++++++++----------------- 3 files changed, 35 insertions(+), 40 deletions(-) diff --git a/doc/md/getting-started.md b/doc/md/getting-started.md index 375ae5733..17c76a663 100755 --- a/doc/md/getting-started.md +++ b/doc/md/getting-started.md @@ -214,7 +214,6 @@ go run entgo.io/ent/cmd/ent init Car Group And then we add the rest of the fields manually: ```go title="/ent/schema/car.go" - // Fields of the Car. func (Car) Fields() []ent.Field { return []ent.Field{ @@ -225,7 +224,6 @@ func (Car) Fields() []ent.Field { ``` ```go title="/ent/schema/group.go" - // Fields of the Group. func (Group) Fields() []ent.Field { return []ent.Field{ @@ -304,7 +302,6 @@ func CreateCars(ctx context.Context, client *ent.Client) (*ent.User, error) { But what about querying the `cars` edge (relation)? Here's how we do it: ```go title="/start/start.go" - import ( "log" @@ -345,7 +342,6 @@ Let's add an inverse edge named `owner` to the `Car` schema, reference it to the in the `User` schema, and run `go generate ./ent`. ```go title="/ent/schema/car.go" - // Edges of the Car. func (Car) Edges() []ent.Edge { return []ent.Edge{ @@ -363,7 +359,6 @@ func (Car) Edges() []ent.Edge { We'll continue the user/cars example above by querying the inverse edge. ```go title="/start/start.go" - import ( "fmt" "log" @@ -378,12 +373,12 @@ func QueryCarUsers(ctx context.Context, a8m *ent.User) error { return fmt.Errorf("failed querying user cars: %w", err) } // Query the inverse edge. - for _, ca := range cars { - owner, err := ca.QueryOwner().Only(ctx) + for _, c := range cars { + owner, err := c.QueryOwner().Only(ctx) if err != nil { - return fmt.Errorf("failed querying car %q owner: %w", ca.Model, err) + return fmt.Errorf("failed querying car %q owner: %w", c.Model, err) } - log.Printf("car %q owner: %q\n", ca.Model, owner.Name) + log.Printf("car %q owner: %q\n", c.Model, owner.Name) } return nil } @@ -401,7 +396,6 @@ of the `users` edge (relation), and the `User` entity has a back-reference/inver relationship named `groups`. Let's define this relationship in our schemas: ```go title="/ent/schema/group.go" - // Edges of the Group. func (Group) Edges() []ent.Edge { return []ent.Edge{ @@ -411,7 +405,6 @@ func (Group) Edges() []ent.Edge { ``` ```go title="/ent/schema/user.go" - // Edges of the User. func (User) Edges() []ent.Edge { return []ent.Edge{ @@ -439,7 +432,6 @@ entities and relations). Let's create the following graph using the framework: ```go title="/start/start.go" - func CreateGraph(ctx context.Context, client *ent.Client) error { // First, create the users. a8m, err := client.User. @@ -458,12 +450,13 @@ func CreateGraph(ctx context.Context, client *ent.Client) error { if err != nil { return err } - // Then, create the cars, and attach them to the users in the creation. + // Then, create the cars, and attach them to the users created above. err = client.Car. Create(). SetModel("Tesla"). - SetRegisteredAt(time.Now()). // ignore the time in the graph. - SetOwner(a8m). // attach this graph to Ariel. + SetRegisteredAt(time.Now()). + // Attach this car to Ariel. + SetOwner(a8m). Exec(ctx) if err != nil { return err @@ -471,8 +464,9 @@ func CreateGraph(ctx context.Context, client *ent.Client) error { err = client.Car. Create(). SetModel("Mazda"). - SetRegisteredAt(time.Now()). // ignore the time in the graph. - SetOwner(a8m). // attach this graph to Ariel. + SetRegisteredAt(time.Now()). + // Attach this car to Ariel. + SetOwner(a8m). Exec(ctx) if err != nil { return err @@ -480,8 +474,9 @@ func CreateGraph(ctx context.Context, client *ent.Client) error { err = client.Car. Create(). SetModel("Ford"). - SetRegisteredAt(time.Now()). // ignore the time in the graph. - SetOwner(neta). // attach this graph to Neta. + SetRegisteredAt(time.Now()). + // Attach this graph to Neta. + SetOwner(neta). Exec(ctx) if err != nil { return err @@ -513,7 +508,6 @@ Now when we have a graph with data, we can run a few queries on it: 1. Get all user's cars within the group named "GitHub": ```go title="/start/start.go" - import ( "log" @@ -540,7 +534,6 @@ Now when we have a graph with data, we can run a few queries on it: 2. Change the query above, so that the source of the traversal is the user *Ariel*: ```go title="/start/start.go" - import ( "log" @@ -579,7 +572,6 @@ Now when we have a graph with data, we can run a few queries on it: 3. Get all groups that have users (query with a look-aside predicate): ```go title="/start/start.go" - import ( "log" diff --git a/doc/md/hooks.md b/doc/md/hooks.md index afec53337..d184785a8 100755 --- a/doc/md/hooks.md +++ b/doc/md/hooks.md @@ -82,7 +82,7 @@ func main() { }) client.User.Create().SetName("a8m").SaveX(ctx) // Output: - // 2020/03/21 10:59:10 Op=Create Type=Card Time=46.23µs ConcreteType=*ent.UserMutation + // 2020/03/21 10:59:10 Op=Create Type=User Time=46.23µs ConcreteType=*ent.UserMutation } ``` diff --git a/examples/start/start.go b/examples/start/start.go index 62d7938bf..ac2b9abea 100644 --- a/examples/start/start.go +++ b/examples/start/start.go @@ -25,7 +25,7 @@ func main() { } defer client.Close() ctx := context.Background() - // run the auto migration tool. + // Run the auto migration tool. if err := client.Schema.Create(ctx); err != nil { log.Fatalf("failed creating schema resources: %v", err) } @@ -87,7 +87,7 @@ func QueryUser(ctx context.Context, client *ent.Client) (*ent.User, error) { } func CreateCars(ctx context.Context, client *ent.Client) (*ent.User, error) { - // creating new car with model "Tesla". + // Create a new car with model "Tesla". tesla, err := client.Car. Create(). SetModel("Tesla"). @@ -97,7 +97,7 @@ func CreateCars(ctx context.Context, client *ent.Client) (*ent.User, error) { return nil, fmt.Errorf("failed creating car: %w", err) } - // creating new car with model "Ford". + // Create a new car with model "Ford". ford, err := client.Car. Create(). SetModel("Ford"). @@ -108,7 +108,7 @@ func CreateCars(ctx context.Context, client *ent.Client) (*ent.User, error) { } log.Println("car was created: ", ford) - // create a new user, and add it the 2 cars. + // Create a new user, and add it the 2 cars. a8m, err := client.User. Create(). SetAge(30). @@ -129,7 +129,7 @@ func QueryCars(ctx context.Context, a8m *ent.User) error { } log.Println("returned cars:", cars) - // what about filtering specific cars. + // What about filtering specific cars. ford, err := a8m.QueryCars(). Where(car.ModelEQ("Ford")). Only(ctx) @@ -146,13 +146,13 @@ func QueryCarUsers(ctx context.Context, a8m *ent.User) error { return fmt.Errorf("failed querying user cars: %w", err) } - // query the inverse edge. - for _, ca := range cars { - owner, err := ca.QueryOwner().Only(ctx) + // Query the inverse edge. + for _, c := range cars { + owner, err := c.QueryOwner().Only(ctx) if err != nil { - return fmt.Errorf("failed querying car %q owner: %w", ca.Model, err) + return fmt.Errorf("failed querying car %q owner: %w", c.Model, err) } - log.Printf("car %q owner: %q\n", ca.Model, owner.Name) + log.Printf("car %q owner: %q\n", c.Model, owner.Name) } return nil } @@ -175,12 +175,13 @@ func CreateGraph(ctx context.Context, client *ent.Client) error { if err != nil { return err } - // Then, create the cars, and attach them to the users in the creation. + // Then, create the cars, and attach them to the users created above. err = client.Car. Create(). SetModel("Tesla"). - SetRegisteredAt(time.Now()). // ignore the time in the graph. - SetOwner(a8m). // attach this graph to Ariel. + SetRegisteredAt(time.Now()). + // Attach this car to Ariel. + SetOwner(a8m). Exec(ctx) if err != nil { return err @@ -188,8 +189,9 @@ func CreateGraph(ctx context.Context, client *ent.Client) error { err = client.Car. Create(). SetModel("Mazda"). - SetRegisteredAt(time.Now()). // ignore the time in the graph. - SetOwner(a8m). // attach this graph to Ariel. + SetRegisteredAt(time.Now()). + // Attach this car to Ariel. + SetOwner(a8m). Exec(ctx) if err != nil { return err @@ -197,8 +199,9 @@ func CreateGraph(ctx context.Context, client *ent.Client) error { err = client.Car. Create(). SetModel("Ford"). - SetRegisteredAt(time.Now()). // ignore the time in the graph. - SetOwner(neta). // attach this graph to Neta. + SetRegisteredAt(time.Now()). + // Attach this cat to Neta. + SetOwner(neta). Exec(ctx) if err != nil { return err